How do I optimize my feed for LightWatch?

Technical guide for creating RSS feeds that look great in LightWatch.

This guide explains how to structure a feed so LightWatch can easily extract media from it and display it as quickly as possible.

The preferred format is RSS 2.0 with the media:content namespace. Atom and JSON Feed are also supported, but RSS 2.0 with media:content gives you the most control over how your content appears.

The ideal post

Here is what a well-optimized post looks like. Everything below explains why.

<item>
  <title>New Typography Posters</title>
  <link>https://designblog.example/posts/typography-posters</link>
  <guid>https://designblog.example/posts/typography-posters</guid>
  <pubDate>Mon, 15 Jan 2024 12:00:00 GMT</pubDate>

  <media:content
    url="https://designblog.example/images/poster-full.jpg"
    type="image/jpeg"
    medium="image"
    width="2400"
    height="3200">
    <media:thumbnail url="https://designblog.example/images/poster-thumb.jpg" />
    <media:description>Helvetica study in red and black</media:description>
  </media:content>

  <media:content
    url="https://designblog.example/videos/process.mp4"
    type="video/mp4"
    medium="video"
    width="1920"
    height="1080">
    <media:thumbnail url="https://designblog.example/videos/process-poster.jpg" />
    <media:description>Design process timelapse</media:description>
  </media:content>
</item>

Feed-level properties

Property Element Required
Title <title> Yes
Canonical URL <link> No

The feed title is what appears in LightWatch as the feed name.

Post properties

Property Element Required
URL <link> Yes
GUID <guid> Yes
Publication date <pubDate> Yes
Title <title> No
Description <description> No
Body <content:encoded> No

The GUID must be unique per post. The publication date is used for ordering. The title is optional but recommended.

Media: the preferred approach

Use media:content elements. This is the most explicit way to declare media and gives LightWatch everything it needs.

Required attributes

Attribute Description
url Direct URL to the image or video file
width Width in pixels. Must be a valid integer.
height Height in pixels. Must be a valid integer.

Providing width and height is preferred. LightWatch uses them for layout. When not provided, the app has to display a default shape which might be wrong, download the image, and then update. Providing the width and height skips that first step and makes the layout smoother. Values like 100% or auto are not valid and will be ignored.

Optional attributes

Attribute Description
type MIME type. Only image/* and video/* are accepted — other types are ignored. Use image/gif for animations.
medium image or video

Thumbnails

You can optionally provide a smaller thumbnail using media:thumbnail nested inside media:content:

<media:content
  url="https://example.com/images/photo-full.jpg"
  type="image/jpeg"
  width="2400"
  height="1600">
  <media:thumbnail url="https://example.com/images/photo-thumb.jpg" />
</media:content>

When provided, LightWatch loads the thumbnail first while browsing and the full-size image when viewing in detail. This is a minor optimization — if you don't provide one, LightWatch uses the full image everywhere and it works fine.

The thumbnail and full-size image must have the same aspect ratio. If they differ, the image will appear distorted when transitioning between views.

Alt text

Use media:description for accessible text:

<media:content url="..." width="2400" height="1600">
  <media:description>A red barn in a wheat field at sunset</media:description>
</media:content>

Media: HTML fallback

If you can't use media:content, LightWatch will extract media from HTML in the <description> and <content:encoded> fields. This is less precise but works for most feeds.

LightWatch checks these sources in order:

  1. media:content elements
  2. media:group contents and thumbnails
  3. Top-level media:thumbnail
  4. RSS <enclosure> elements
  5. HTML in <description>
  6. HTML in <content:encoded>

Earlier sources take priority. If you provide media:content, the HTML in your description won't be parsed for additional media.

Images in HTML

LightWatch checks these attributes in order:

  1. <picture> <source> elements (scans all sources for srcset)
  2. srcset on the <img> tag
  3. data-srcset (lazy-loaded fallback, parsed the same way)
  4. src
  5. data-src (lazy-loaded fallback)

When srcset or <picture> sources are available, LightWatch selects the largest image by width descriptor for full-size display, and the smallest image >= 600px wide as the thumbnail.

For the best results, include width and height attributes on your <img> tags:

<img
  src="photo-800.jpg"
  srcset="photo-600.jpg 600w, photo-1200.jpg 1200w, photo-2400.jpg 2400w"
  alt="Abstract painting in acrylic"
  width="2400"
  height="1600"
/>

LightWatch extracts alt text from these attributes in order: aria-label, alt, title.

Videos in HTML

LightWatch extracts videos from <video> elements:

<video
  src="https://example.com/videos/process.mp4"
  poster="https://example.com/videos/process-poster.jpg"
  width="1920"
  height="1080"
  title="Design process video"
>
  <source src="https://example.com/videos/process.mp4" type="video/mp4" />
</video>

Including a poster image is preferred. LightWatch uses it as a preview thumbnail, which provides a better experience than loading the video to generate one.

The poster must match the video aspect ratio to prevent distortion.

Source attribution

If your feed aggregates content from multiple authors (like a community feed or a curated collection), you can attribute individual posts to their source:

<item>
  <source url="https://artist.example/feed.xml">Artist Name</source>
  <!-- ... -->
</item>

LightWatch displays the source and lets users follow the original feed directly from the gallery.

Image sizes

Larger, well-optimized images provide a better visual experience. Use whatever size makes sense for your content, but keep file sizes reasonable.

Supported image formats

  • JPEG (.jpg, .jpeg)
  • PNG (.png)
  • WebP (.webp)
  • HEIC/HEIF (.heic, .heif)
  • GIF (.gif) — displayed as animations

SVG is not supported.

Supported video formats

File extensions: .mp4, .mov, .webm, .m4v, .m3u8 (HLS), .avi, .mkv, .mpg, .mpeg

MIME types: video/*, application/x-mpegurl (HLS), application/dash+xml (DASH)