Media Manager

Overview

media-manager is a command-line tool that inspects and repairs a Plex-style media library. It identifies movies and episodes, checks container integrity, measures audio/video lip-sync, detects permanent black borders, selects and synchronizes subtitles, and records every decision in SQLite.

The learned components do the parts that rules cannot: SyncNet, a neural lip-sync model, estimates audio/video drift by comparing mouth motion against the audio track, and Silero VAD selects speech-rich windows to test.

The published distribution is stateful-media-manager, currently at version 0.6.0, under MIT. The source is public.

The problem

A media library degrades in ways that are individually small and collectively ruinous: audio drifts a few hundred milliseconds out of sync, a film is letterboxed inside its own frame, a subtitle track runs seconds ahead of the dialogue.

Each is detectable in principle. The difficulty is that every fix is destructive. A tool that acts on weak evidence does not improve a library; it damages it in a way nobody notices until playback.

The safety model

The whole design follows from one rule: prefer a review result over an uncertain destructive change.

Transformations are built in a private working directory and verified with ffprobe before an atomic replacement. If analysis, transformation, or verification fails, the original file is untouched. Outcomes the tool is not confident about are recorded as needs_review, insufficient_evidence, or unavailable, never silently converted into a correction.

That extends to the model output. SyncNet produces a drift estimate, not a decision. A correction is applied only when the estimate clears coverage-gated robust estimation across multiple sampled windows; a single confident-looking inference is not enough.

Applying the models

SyncNet is expensive, so the pipeline does not run it on every frame. Silero VAD identifies windows with actual speech, the only places lip-sync is measurable, and the model tests short, speech-rich clips rather than the full runtime. FFmpeg silence detection is the fallback when Silero is unavailable. PySceneDetect is pinned below 0.7 because syncnet-python still imports its legacy VideoManager API.

Every completed candidate window is checkpointed, so a long CPU inference run survives a pause, a crash, or a reboot and resumes where it stopped. Model weights are not bundled; a setup command fetches them into the library’s private state directory.

The A/V stack is an optional extra. The tool is useful without it, and installing PyTorch is a choice the user makes deliberately.

State as a first-class concern

The manager is stateful by design. Completed stages and intra-stage checkpoints persist in library-local SQLite, so work is never repeated and provenance for each decision is recoverable. An advisory lock permits one mutating process per library while leaving read-only status commands and pause available from another terminal.

What I directed versus what the model produced

I designed the stage pipeline, the safety model, the evidence thresholds, and the checkpointing scheme, and I chose SyncNet and Silero for their specific roles. AI coding tools wrote a large share of the implementation against that design. The judgment about when evidence is strong enough to modify someone’s files is mine, and it is deliberately conservative.

Result

The tool ships as an installable CLI with an authenticated web dashboard for live status, review detail, history, and checkpoint-safe run control, plus Docker and Compose packaging. It runs on Linux against Python 3.11+.

What I learned

Applying a model to real files taught me that inference accuracy is the easy half. The hard half is deciding what an estimate entitles you to do. Most of the code exists to answer that question conservatively, and the tool is more useful because it frequently declines to act.