Processing
When Odeion discovers new media files during a library scan, it enqueues a series of background processing tasks for each file. These tasks run automatically and can be monitored from the admin panel under Tasks.
Processing Pipeline
Section titled “Processing Pipeline”Each new media file goes through four stages, executed in order:
Probe → Media Extract → Analyze Segments → TrickplayEach stage depends on the previous one completing successfully. If a stage fails, downstream stages will not run until it succeeds (either automatically on retry or after a manual retry from the admin panel).
The probe stage runs ffprobe on the media file to extract technical metadata. This includes:
Video streams: codec, resolution, bit depth, frame rate, pixel format, color space, HDR format (Dolby Vision, HDR10, HLG, or SDR).
Audio streams: codec, channels, channel layout, sample rate, language, default/forced flags.
Subtitle streams: codec (text or bitmap), language, default/forced/hearing-impaired flags.
Container: format, overall bitrate, duration.
Chapters: chapter markers and titles embedded in the file.
This metadata is stored in the database and used by the transcoder, subtitle system, and segment analyzer.
Media Extract
Section titled “Media Extract”The media extract stage runs a single FFmpeg pass over the file to produce up to three outputs:
Still thumbnail (JPEG): A single frame captured at roughly 10% of the video duration. Used as a fallback poster or backdrop image when no metadata artwork is available. Output resolution is 400px wide.
Seek preview (animated WebP): A looping animation of the entire video at low resolution (320px wide, 1 fps by default). Used by the web and app players to show a visual preview when scrubbing through the progress bar. These files are typically 1-5 MB depending on video length.
Embedded subtitle extraction: Any text-based subtitle streams (SRT, ASS, SSA, WebVTT, MOV text) are extracted to individual SRT files. Bitmap subtitle formats (PGS, DVD, DVB) are tracked in the database but not extracted since they require burn-in during transcoding.
Media extract has a concurrency limit of 1 because it is IO-intensive. It skips audio-only files and very short content (under 10 seconds).
Analyze Segments
Section titled “Analyze Segments”The segment analysis stage tries to detect skippable segments (intros, outros, recaps, previews) using three methods:
Chapter-based detection looks at chapter markers in the file and matches their titles against known patterns like “Intro”, “Opening”, “Credits”, “Recap”, “Preview”, and similar variations. This works for both movies and episodes.
IntroDB lookup queries a crowdsourced database of intro/outro timestamps using the content’s TMDB ID. This only works for TV episodes and requires a TMDB match.
Audio fingerprinting uses FFmpeg’s chromaprint feature to detect shared audio segments across episodes in the same season. Odeion fingerprints the beginning and end of each episode, then compares fingerprints across the season to find segments that appear in multiple episodes (which are typically intros or outros). This requires FFmpeg to be compiled with chromaprint support.
When segments are detected, the player apps show a “Skip Intro” or “Skip Credits” button during playback.
Trickplay
Section titled “Trickplay”The trickplay stage generates sprite sheets, which are grids of small thumbnail frames captured at regular intervals throughout the video. These power the timeline thumbnail preview that appears when you hover over or scrub through the progress bar in the player.
Unlike the animated seek preview from the media extract stage (which produces a single low-resolution animation), trickplay sprites are individual still frames arranged into JPEG sheet images. This gives the player a crisp thumbnail for any point in the video.
Trickplay uses the transcoder pool system for GPU acceleration when a pool is available, and falls back to CPU-only processing otherwise. It skips audio-only files and content shorter than 30 seconds.
Configuration
Section titled “Configuration”Several processing features can be toggled on or off from Admin > Settings > Processing or through the kill switches:
| Setting | Default | Description |
|---|---|---|
| Seek preview generation | Enabled | Generate animated WebP seek previews |
| Subtitle extraction | Enabled | Extract text-based embedded subtitles to SRT |
| Seek preview FPS | 1.0 | Frame rate for animated previews |
| Seek preview width | 320 | Width in pixels for animated previews |
| Trickplay generation | Enabled | Generate sprite sheet thumbnails for timeline previews |
| Trickplay interval | 5 seconds | Time between captured thumbnail frames |
| Trickplay width | 320 | Width in pixels for each thumbnail in the sprite sheet |
| Scan workers | Auto (CPU/2, max 4) | Concurrent file probe workers during scan |
| Scan batch size | Auto (RAM-based) | Number of files per scan batch |
Monitoring Tasks
Section titled “Monitoring Tasks”The admin panel’s Tasks page shows all background processing tasks with their status (pending, running, completed, failed, cancelled), progress percentage, and any error messages. From this page you can:
- Retry individual failed tasks or all failed tasks at once
- Cancel pending tasks individually or in bulk
- View task statistics and queue depth