StarPunk/docs/decisions/ADR-059-full-feed-media-standardization.md

ADR-059: Full Feed Media Standardization (Option 3)

Status

Proposed (For v1.3.0 Backlog)

Context

StarPunk v1.2.0 introduced media attachments for notes (images). The initial implementation embeds media as HTML in feed description fields. Option 2 (implemented in v1.2.x) adds Media RSS extension elements and JSON Feed image fields for better feed reader compatibility.

This ADR documents Option 3: Full Standardization, which provides comprehensive media support across all syndication formats, including video, audio, and advanced features. This is planned for v1.3.0 or later.

Decision

Document the scope of "Full Standardization" for feed media support to be implemented in a future release. This option goes beyond Option 2's basic Media RSS support to include:

1. Complete Media RSS Specification Support
2. Podcast RSS Support (RSS 2.0 enclosures for audio)
3. Video Support
4. Multiple Image Sizes/Thumbnails
5. Full JSON Feed 1.1 Media Compliance

Scope of Full Standardization

1. Complete Media RSS Implementation

Research Required: Full Media RSS specification at https://www.rssboard.org/media-rss

Elements to Implement:

• <media:content> with full attribute support:

  • url (required) - Direct URL to media file
  • fileSize - Size in bytes
  • type - MIME type
  • medium - Type: "image", "audio", "video", "document", "executable"
  • isDefault - Boolean for default rendition
  • expression - "full", "sample", "nonstop"
  • bitrate - Kilobits per second
  • framerate - Frames per second (video)
  • samplingrate - Samples per second (audio)
  • channels - Audio channels
  • duration - Seconds
  • height / width - Dimensions in pixels
  • lang - RFC-3066 language code

• <media:group> - Container for multiple renditions of same content

• <media:thumbnail> - Multiple sizes with url, width, height, time

• <media:title> - Media title (type="plain" or "html")

• <media:description> - Media description (type="plain" or "html")

• <media:keywords> - Comma-separated keywords

• <media:category> - Categorization with scheme attribute

• <media:credit> - Credit attribution with role and scheme

• <media:copyright> - Copyright information

• <media:rating> - Content rating (scheme-based)

• <media:hash> - MD5/SHA-1 hash for integrity

• <media:player> - Embeddable player URL

Effort Estimate: 8-12 hours

2. Podcast RSS Support

Research Required:

• Apple Podcast RSS specification
• Google Podcast RSS requirements
• Podcast Index namespace (podcast:)

Elements to Implement:

• iTunes namespace (xmlns:itunes="http://www.itunes.com/dtds/podcast-1.0.dtd"):

  • <itunes:summary> - Episode summary
  • <itunes:duration> - Audio duration (HH:MM:SS)
  • <itunes:image> - Episode artwork
  • <itunes:explicit> - Content rating
  • <itunes:episode> - Episode number
  • <itunes:season> - Season number
  • <itunes:episodeType> - "full", "trailer", "bonus"
  • <itunes:author> - Author name
  • <itunes:owner> - Owner contact

• Standard RSS <enclosure> for audio:

  • url - Direct audio file URL
  • length - File size in bytes
  • type - MIME type (audio/mpeg, audio/mp4, etc.)

Database Changes:

• Add duration column to note_media table
• Add media_type enum (image, audio, video)
• Consider podcast_metadata table for series-level data

Effort Estimate: 10-16 hours

3. Video Support

Research Required:

• Video hosting considerations (storage, bandwidth)
• Supported formats (mp4, webm, ogg)
• Transcoding requirements
• Poster image generation

Implementation Scope:

• Accept video uploads via Micropub media endpoint

• Generate poster thumbnails automatically

• Include in Media RSS with proper video attributes:

  • medium="video"
  • framerate, duration, bitrate
  • Associated <media:thumbnail> for poster

• HTML5 <video> element in feed description

• Consider video hosting limits (file size, duration)

Database Changes:

• Video-specific metadata in media table
• Poster image path
• Transcoding status (if needed)

Effort Estimate: 16-24 hours (significant)

4. Multiple Image Sizes (Thumbnails)

Research Required:

• Responsive image best practices
• WebP generation
• srcset/sizes patterns

Implementation Scope:

• Generate multiple sizes on upload:

  • Thumbnail: 150x150 (square crop)
  • Small: 320px width
  • Medium: 640px width
  • Large: 1280px width
  • Original: preserved

• Store all sizes in media_variants table

• Include in Media RSS:

  <media:group>
    <media:content url="large.jpg" isDefault="true" width="1280" />
    <media:content url="medium.jpg" width="640" />
    <media:content url="small.jpg" width="320" />
  </media:group>
  <media:thumbnail url="thumb.jpg" width="150" height="150" />
  

• JSON Feed: Use image for default, include variants in _starpunk extension

Database Changes:

• media_variants table: media_id, variant_type, path, width, height, size_bytes
• Add has_variants boolean to media table

Effort Estimate: 8-12 hours

5. Full JSON Feed 1.1 Media Compliance

Research Required: JSON Feed 1.1 specification for extensions

Implementation Scope:

• Top-level image field (URL of first image, per spec)
• Top-level banner_image if applicable
• Item-level image field (main/featured image)
• Item-level banner_image for posts with banners
• Complete attachments array:

  {
    "url": "https://example.com/media/image.jpg",
    "mime_type": "image/jpeg",
    "title": "Image caption",
    "size_in_bytes": 245760,
    "duration_in_seconds": null
  }
  

• Audio attachments with duration_in_seconds
• Video attachments (if supported)

Effort Estimate: 4-6 hours

6. ATOM Feed Media Extensions

Research Required:

• ATOM Media extension namespace
• <link rel="enclosure"> best practices

Implementation Scope:

• <link rel="enclosure"> for each media item
• type attribute with MIME type
• length attribute with file size
• title attribute with caption
• Consider <link rel="related"> for thumbnails

Effort Estimate: 3-5 hours

Total Effort Estimate

Feature	Minimum	Maximum
Complete Media RSS	8 hours	12 hours
Podcast RSS Support	10 hours	16 hours
Video Support	16 hours	24 hours
Multiple Image Sizes	8 hours	12 hours
JSON Feed Compliance	4 hours	6 hours
ATOM Extensions	3 hours	5 hours
Total	49 hours	75 hours

Note: Video support is the most complex feature and could be deferred to v1.4.0 "Media" release.

Prerequisites

Before implementing Full Standardization:

1. Option 2 Complete: Basic Media RSS and JSON Feed image field
2. Image Optimization: ADR-058 image optimization strategy implemented
3. Media Storage Architecture: Clear path for large file storage
4. Test Infrastructure: Feed validation tests in place

Implementation Phases

Phase A: Enhanced Image Support (v1.3.0)

• Multiple image sizes/thumbnails
• Full Media RSS for images
• Enhanced JSON Feed attachments
• Effort: 12-18 hours

Phase B: Audio Support (v1.3.x or v1.4.0)

• Podcast RSS implementation
• Audio duration extraction
• iTunes namespace
• Effort: 10-16 hours

Phase C: Video Support (v1.4.0 "Media")

• Video upload handling
• Poster generation
• Video in feeds
• Effort: 16-24 hours

Consequences

Positive

• Best-in-class feed reader compatibility
• Podcast distribution capability
• Video content support
• Professional media syndication
• Future-proof architecture

Negative

• Significant implementation effort (50-75 hours total)
• Increased storage requirements
• More complex feed generation
• Processing overhead for image variants
• Larger codebase to maintain

Neutral

• Aligns with media-focused v1.4.0 roadmap
• Phased implementation possible
• Optional features can be configuration-gated

Alternatives Considered

Alternative 1: Minimal Enhancement (Option 2 Only)

Just implement basic Media RSS and JSON Feed image field.

• Pros: Low effort, immediate benefit
• Cons: Misses podcast/video opportunity

Alternative 2: Third-Party Media Service

Use external service (Cloudinary, etc.) for media processing.

• Pros: Offloads complexity
• Cons: External dependency, cost, data ownership concerns

Alternative 3: Plugin Architecture

Make media support pluggable for advanced features.

• Pros: Keeps core simple
• Cons: Added architectural complexity

References

• Media RSS Specification
• JSON Feed 1.1 Specification
• Apple Podcast RSS Requirements
• Podcast Index Namespace
• RSS 2.0 Enclosure Specification
• ADR-057: Media Attachment Model
• ADR-058: Image Optimization Strategy

Decision

This ADR documents the scope of Full Standardization (Option 3) for the project backlog. Implementation should be scheduled for v1.3.0 and v1.4.0 releases according to the phased approach outlined above.

Immediate Action: Implement Option 2 (ADR-060) for v1.2.x release. Future Action: Review and refine this scope when scheduling v1.3.0 work.