Post-Processing Services

Post-processing services in Riven enhance your downloaded media with additional features like subtitles and media analysis.

Available Services

• Subtitles - Automatically fetch subtitles for your media
• Media Analysis - Analyze media files for metadata

Subtitles

Riven can automatically fetch subtitles for your downloaded media from various providers.

Configuration

Subtitle settings can be found in the web UI under Settings → Post-Processing → Subtitles.

• enabled (boolean): Enable or disable subtitle fetching

  • Example: true
  • Default: false

• languages (list of strings): Languages to fetch subtitles for

  • Example: ["en", "es", "fr"]
  • Uses ISO 639-1 language codes
  • Default: ["en"]

Subtitle Providers

Riven supports multiple subtitle providers:

OpenSubtitles

Free subtitle database with extensive coverage.

• enabled (boolean): Enable OpenSubtitles provider
• api_key (string): Your OpenSubtitles API key (optional but recommended)
  • Get one from: https://www.opensubtitles.com/en/consumers

Subscene

Alternative subtitle source.

• enabled (boolean): Enable Subscene provider

Other Providers

Additional providers may be available depending on your Riven version. Check the web UI for the complete list.

How Subtitles Work

1. Trigger: After a file is successfully downloaded and registered in VFS
2. Search: Riven searches enabled subtitle providers for matching subtitles
3. Download: Best matching subtitles are downloaded
4. Storage: Subtitles are saved alongside the media file
5. Format: Usually SRT format, compatible with all media servers

Subtitle File Naming

Subtitles are saved with standard naming conventions:

Movie.Name.2024.1080p.mkv
Movie.Name.2024.1080p.en.srt
Movie.Name.2024.1080p.es.srt

Your media server should automatically detect and display these.

Troubleshooting Subtitles

No subtitles found

Possible causes:

• Movie/show too new (subtitles not available yet)
• Incorrect language codes
• Provider down or rate limited

Solutions:

1. Enable multiple providers for redundancy
2. Check language codes are correct (ISO 639-1)
3. Wait a few hours/days for new releases
4. Manually download from provider website if needed

Wrong subtitles

Possible causes:

• Multiple versions of the same release
• Subtitle file matches wrong release

Solutions:

1. Manually download correct subtitles
2. Check if using correct release group in torrent selection

Media Analysis

The Media Analysis service analyzes downloaded media files to extract technical metadata.

What It Does

• Video Codec Detection: Identifies H.264, H.265, VP9, etc.
• Audio Codec Detection: AAC, DTS, TrueHD, etc.
• Resolution Detection: 720p, 1080p, 4K, etc.
• HDR Detection: HDR, HDR10, Dolby Vision
• Audio Channels: Stereo, 5.1, 7.1, Atmos

Configuration

• enabled (boolean): Enable media analysis
  • Example: true
  • Default: false

Use Cases

1. Quality Verification: Ensure downloaded file matches expected quality
2. Filtering: Filter out files with incompatible codecs
3. Metadata Enrichment: Enhance Riven's database with technical details
4. Debugging: Identify why certain files won't play

Technical Details

Media analysis uses ffprobe (part of FFmpeg) to analyze files:

# Riven essentially runs:
ffprobe -v quiet -print_format json -show_format -show_streams file.mkv

The results are stored in the database and available via the API.

Environment Variables

Configure post-processing via environment variables:

# Subtitles
RIVEN_POST_PROCESSING_SUBTITLES_ENABLED=true
RIVEN_POST_PROCESSING_SUBTITLES_LANGUAGES=["en","es"]

# Providers
RIVEN_POST_PROCESSING_SUBTITLES_OPENSUBTITLES_ENABLED=true
RIVEN_POST_PROCESSING_SUBTITLES_OPENSUBTITLES_API_KEY=your_key_here

# Media Analysis
RIVEN_POST_PROCESSING_MEDIA_ANALYSIS_ENABLED=true

Workflow Integration

Post-processing services run between the "Downloaded" and "Completed" states:

Downloaded → Post-Processing (Subtitles, Analysis) → Filesystem (VFS) → Completed

If post-processing fails, the item still proceeds to "Completed" - post-processing is optional.

Best Practices

Subtitles

1. Enable multiple providers: Redundancy helps when one provider is down
2. Use API keys: Better rate limits and reliability
3. Limit languages: Only fetch languages you actually need (saves bandwidth)
4. Check naming: Ensure your media server recognizes the subtitle files

Media Analysis

1. Use selectively: Only enable if you need the metadata
2. Monitor bandwidth: Analysis downloads file headers
3. Check compatibility: Ensure your debrid service allows range requests

Future Enhancements

Potential future post-processing features:

• Custom Scripts: Run custom scripts on downloaded media
• Transcoding: Convert media to specific formats
• NFO Generation: Create .nfo files for media servers
• Artwork Download: Fetch posters, fanart, etc.

See Also

• Architecture - Understanding the workflow
• Troubleshooting - Common issues
• Filesystem (VFS) - Where media files end up