No description
  • Python 97.8%
  • Nix 1.4%
  • Dockerfile 0.4%
  • Shell 0.4%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
2026-11-03 01:08:44 +01:00
docker feat: schedule the container with a cron expression 2026-11-03 00:23:56 +01:00
scripts fix: render canonical pause tags for TTS backends 2026-11-03 01:08:42 +01:00
skills docs: document pause-tag rendering and breath control 2026-11-03 01:08:44 +01:00
.dockerignore feat: add Docker image and compose scheduler 2026-11-02 19:08:08 +01:00
.env.example feat: support server config dir, sources.jsonc and cron runs 2026-11-02 18:15:44 +01:00
.envrc feat: initial lecture pipeline import 2026-10-27 22:20:16 +01:00
.gitignore feat: add Docker image and compose scheduler 2026-11-02 19:08:08 +01:00
AGENTS.md docs: document pause-tag rendering and breath control 2026-11-03 01:08:44 +01:00
compose.env.example feat: schedule the container with a cron expression 2026-11-03 00:23:56 +01:00
conf.example.jsonc docs: document pause-tag rendering and breath control 2026-11-03 01:08:44 +01:00
docker-compose.yaml feat: schedule the container with a cron expression 2026-11-03 00:23:56 +01:00
Dockerfile feat: schedule the container with a cron expression 2026-11-03 00:23:56 +01:00
flake.lock feat: initial lecture pipeline import 2026-10-27 22:20:16 +01:00
flake.nix feat: schedule the container with a cron expression 2026-11-03 00:23:56 +01:00
README.md docs: document pause-tag rendering and breath control 2026-11-03 01:08:44 +01:00
sources.example.jsonc feat: support server config dir, sources.jsonc and cron runs 2026-11-02 18:15:44 +01:00

yt-down-with-subs

Automated pipeline that keeps a set of YouTube playlists mirrored locally (video + sidecar subtitles), fills in missing subtitles with Whisper, optionally corrects transcription mishearings with an LLM, produces structured Czech study notes, and can render those notes to spoken text and audio.

Programs

Five independent CLI programs, an auxiliary Markdown → PDF converter, and a master orchestrator, all built by a single nix flake:

Command Role
downloader Download playlists/videos with sidecar subtitles; dedupe rolling auto-captions
transcribe Video → Whisper-compatible API → timestamped SRT (unmodified project)
correct-transcript Opt-in LLM correction of mishearings in an SRT
summarize LLM study notes from an SRT (single call or map-reduce)
summarize-pdf Render the Markdown notes to print-friendly PDFs
tts Rewrite notes into spoken Czech and synthesize audio (OmniVoice or Google Cloud TTS)
pipeline Orchestrate the stages incrementally

Layout

flake.nix, flake.lock      single flake for all programs
Dockerfile, docker-compose.yaml
                           container image and compose service
docker/entrypoint.sh       scheduled/once container runner
compose.env.example        host paths and cron schedule for compose
conf.example.jsonc         committed template for regular settings
sources.example.jsonc      committed template for playlist sources
.env.example               committed template for credentials
~/.config/lecture-compressor/
  conf.jsonc               endpoints, models, voices and tuning
  sources.jsonc            playlist list with per-playlist options
  .env                     credentials only (chmod 600)
  pipeline.lock            created while a pipeline run is active
scripts/downloader/        yt-dlp + subtitle dedup (Python)
scripts/transcribe/        transcribe project (source unmodified)
scripts/correct_transcript/
scripts/summarize/
scripts/tts/               spoken text + OmniVoice/Google TTS backends
scripts/pipeline/          master orchestrator
skills/                    LLM skill prompts
content/                   products (location from pipeline.content_dir)
  <Playlist>/              *.mp4 + *.cs.srt (kept together for players)
  <Playlist>/slides/       optional lecture PDFs (terminology reference)
  <Playlist>/summaries/    generated *.md notes (plus *.pdf with the pdf option)
    tts/                   TTS-friendly plain text
    audio/                 synthesized audio

Videos and their subtitle sidecars stay in the same folder so mpv/VLC discover them automatically; summaries go into a summaries/ subfolder. A playlist's folder name is its sources.jsonc label, not the title YouTube reports.

Setup

  1. Create the configuration directory and copy the templates:

    mkdir -p ~/.config/lecture-compressor
    cp conf.example.jsonc    ~/.config/lecture-compressor/conf.jsonc
    cp sources.example.jsonc ~/.config/lecture-compressor/sources.jsonc
    cp .env.example          ~/.config/lecture-compressor/.env
    chmod 600 ~/.config/lecture-compressor/.env
    

    In conf.jsonc, set pipeline.content_dir (absolute is recommended for cron), the endpoints and models:

    • transcribe.base_url / transcribe.model (OpenAI-compatible /audio/transcriptions endpoint);
    • llm.base_url / llm.model (chat-completions endpoint used by correct-transcript, summarize and tts).

    In .env, fill in the credentials: TRANSCRIBE_API_KEY, LLM_API_KEY, and the Google Cloud TTS credentials when that backend is used. Environment variables with the legacy names still override conf.jsonc for one-off runs, and every program accepts --config PATH.

    PIPELINE_CONFIG_DIR or pipeline --config-dir PATH selects a different directory.

  2. List playlists in sources.jsonc. The label becomes the content folder name. Options use the same names as the legacy links.md flags:

    Option Effect
    rename Canonical lecture names; prezentace items are skipped
    correct Run LLM correction for this playlist
    pdf Also export PDF notes for this playlist
    audio Run the TTS stage for this playlist
    {
      "sources": [
        {
          "label": "AVS playlist",
          "url": "https://www.youtube.com/playlist?list=...",
          "options": ["rename", "correct", "pdf", "audio"]
        },
        {
          "label": "TIN playlist",
          "url": "https://www.youtube.com/playlist?list=...",
          "options": ["rename"]
        }
      ]
    }
    

    Set "enabled": false on an entry to keep it without downloading it. A legacy links.md (label: url | option ...) is still accepted when no sources.jsonc exists; --sources selects a file explicitly.

    download, transcribe and summarize always run. A playlist without options still gets transcripts and notes; the optional stages apply only where listed. pipeline --correct, --pdf and --audio enable the corresponding option for every playlist for one run.

Usage

nix develop                       # enter the environment

pipeline                          # download → transcribe → summarize
pipeline --correct                # ... plus correction for every playlist
pipeline --pdf                    # ... plus PDFs for every playlist
pipeline --audio                  # ... plus TTS for every playlist
pipeline --only download,summarize
pipeline --playlist AVS           # only download sources labelled "AVS…"
pipeline --dry-run                # print the commands without running
pipeline --rename-existing        # one-off rename of the current content
pipeline --config-dir ./cfg       # use another configuration directory
nix run .#pipeline -- --correct   # same, without a dev shell

pipeline reads conf.jsonc, sources.jsonc, .env and the run lock from ~/.config/lecture-compressor by default ($PIPELINE_CONFIG_DIR or --config-dir override it). The content directory comes from pipeline.content_dir; the positional root still wins when given.

Individual programs:

downloader URL... [-o content] [--sub-langs cs] [--rename] [--folder NAME]
downloader --rename-existing -o content       # no URL needed
transcribe VIDEO
correct-transcript VIDEO.cs.srt      # writes VIDEO.cs.corrected.srt
correct-transcript VIDEO.cs.srt --slides path/to/slides/
summarize VIDEO.cs.srt               # writes summaries/VIDEO.cs.md
summarize VIDEO.cs.srt --pdf         # ... and summaries/VIDEO.cs.pdf
summarize-pdf content/AVS            # convert existing notes (recursive)
summarize-pdf note.md -o note.pdf    # explicit destination
tts content/AVS/summaries            # spoken text + audio for existing notes
tts note.md --only text              # only the LLM rewrite
tts note.md --only audio             # only audio from existing spoken text

Unattended runs

pipeline is designed to be started repeatedly by cron or a systemd timer. Before doing any work it takes a non-blocking lock at <config-dir>/pipeline.lock; if another run still owns it, the new run prints a message and exits 0 without touching the content tree.

Example crontab entry (every 30 minutes, appending to a log):

*/30 * * * * /run/current-system/sw/bin/pipeline --config-dir "$HOME/.config/lecture-compressor" >> "$HOME/.local/state/lecture-compressor/pipeline.log" 2>&1

Before enabling it:

mkdir -p ~/.local/state/lecture-compressor
pipeline --config-dir ~/.config/lecture-compressor --dry-run

Notes:

  • Use the installed Nix wrapper (command -v pipeline from the profile) so PIPELINE_SKILLS_DIR and the child tools are on PATH. Do not rely on nix develop in cron.
  • HOME must belong to the user that owns the configuration and content directories. Prefer absolute paths in conf.jsonc for pipeline.content_dir and tts.omnivoice.infer_batch.
  • Exit status: 0 success or lock skip, 1 one or more stage failures, 2 configuration/source errors. Cron mails the output when MAILTO is set.
  • Keep .env and conf.jsonc readable only by that user (chmod 600).

Docker

The image builds the entire Nix closure for pipeline — the child programs, ffmpeg, yt-dlp, PDF fonts and skills — so the host needs only Docker. Configuration, sources, credentials and content stay outside the image and are bind-mounted.

  1. Prepare ~/.config/lecture-compressor as described in Setup.

  2. Copy compose.env.example to compose.env and set absolute paths and the cron schedule:

    cp compose.env.example compose.env
    $EDITOR compose.env
    

    PIPELINE_CRON uses the standard five-field syntax. Examples: */30 * * * * (every 30 minutes), 0 3 * * * (daily at 03:00), 15 * * * * (hourly at :15). Cron times use the container time zone (TZ, default UTC); the image includes timezone data.

  3. Build and start the scheduler:

    docker compose --env-file compose.env up -d --build
    docker compose --env-file compose.env logs -f pipeline
    

The service runs scheduled mode through supercronic (default */30 * * * *). The first run happens at the next matching time, not immediately on container start. Supercronic does not overlap jobs by default, and the config-directory lock protects against manual runs.

Run it once instead:

docker compose --env-file compose.env run --rm pipeline once
docker compose --env-file compose.env run --rm pipeline once --force

once returns the pipeline exit status, so it can also be driven by a host cron/systemd timer instead of the built-in schedule.

Mounts:

Host Container Purpose
LECTURE_CONFIG_DIR /config conf.jsonc, sources.jsonc, .env, pipeline.lock
LECTURE_CONTENT_DIR /content playlist folders, subtitles, summaries, audio
pipeline-cache volume /cache yt-dlp/HuggingFace caches (HOME)

PIPELINE_CONTENT_DIR=/content overrides pipeline.content_dir inside the container; the mounted content directory is the effective root.

Notes:

  • The config directory must be writable: the pipeline creates pipeline.lock there.
  • The container runs as root by default, so generated files on the host are root-owned. Uncomment user: in docker-compose.yaml, set PUID/PGID, and make the config/content directories and cache volume writable by that user.
  • OmniVoice is not part of the flake and is not installed in the image. Set tts.backend to google (credentials in the mounted .env), or mount a working omnivoice-infer-batch and point tts.omnivoice.infer_batch at its container path.
  • GOOGLE_APPLICATION_CREDENTIALS and other credential files must be mounted into the container and referenced by their container path in .env.
  • Container logs use Docker's json-file driver with 10 MB × 3 rotation; adjust the logging block in docker-compose.yaml for a different policy.
  • The image is about 2.2 GB because it carries the complete ffmpeg and Python runtime closure.

Lecture naming convention

Some playlists name each recording after its metadata:

TIN, kamera, 14.9.2026, 11_00, D105 (přednáška).mp4
MSP, kamera, 13.10.2026, 10_00, E112.mp4
TIN, prezentace, 14.9.2026, 11_00, D105 (přednáška).mp4

Sorted lexicographically, these names group by day-of-month or time of day, not by date. The playlist's content folder is named after its sources.jsonc label (passed to the downloader as --folder), so the folder does not change when YouTube renames a playlist. Adding rename to its options enables two further behaviours:

  • ..., prezentace, ... items are not downloaded (they are checked again on every run, like active livestreams);
  • new recordings are renamed to <subject>_<yyyy>-<mm>-<dd>[_<specifier>] (TIN_2026-09-14_přednáška). Time and room code are dropped; the parenthesised specifier is preserved when present. Subtitle sidecars, summaries/<name>.md/.pdf, summaries/tts/ and summaries/audio/ are renamed with the video.

Titles that do not match the pattern completely are left untouched. If two recordings map to the same name, the later one gets _2, _3, … rather than overwriting anything.

Existing recordings are not renamed automatically on every run. Use pipeline --rename-existing once after enabling the option; it scans the whole content root and is idempotent. The downloader equivalent is downloader --rename-existing -o content (no URL needed).

Slides as a terminology reference

The correction stage can use lecture slides to fix technical terms, names and notation. Put the PDFs in the playlist's slides/ subfolder (content/<Playlist>/slides/*.pdf); pipeline --correct picks them up automatically and applies them to every lecture in that playlist. For a single run, correct-transcript --slides DIR (or pipeline --slides-dir DIR) overrides the convention.

The directory's text is distilled once into a terminology brief and cached as slides/.correct-reference.md, keyed by a digest of the PDFs, so later runs reuse it. Small decks are used verbatim; larger ones go through the LLM. Tuning: CORRECT_REFERENCE_TOKENS (default 6000), correct-transcript --refresh-reference, --no-cache. Image-only or scanned PDFs yield little text (no OCR is performed).

Incremental behaviour

  • download uses yt-dlp's archive (content/.yt-down-archive.txt): only videos added since the last run are fetched. Active livestreams are skipped rather than downloaded in real time; the next run picks them up once YouTube serves them as VOD. Scheduled/premiere livestreams and other per-video errors are logged and skipped — they never abort the run. Playlists marked | rename additionally skip presentation recordings and rename new lectures canonically (see above).
  • transcribe runs only for videos with no subtitle sidecar at all (a YouTube .cs.srt counts as present, so no redundant Whisper calls).
  • correct writes <base>.corrected.srt and skips it when it is newer than the source.
  • summarize prefers the corrected subtitle, otherwise .cs.srt, otherwise .srt, and writes summaries/<base>.md (skipped when newer than the input). With the pdf option it also writes summaries/<base>.pdf; the conversion is likewise skipped while the PDF is newer than the notes, so enabling the option on an existing tree catches up without regenerating summaries (--force overrides).
  • tts rewrites each notes file to summaries/tts/<base>.txt (skipped while newer than the notes) and synthesizes summaries/audio/<base>.<ext> (skipped while newer than the spoken text). OmniVoice audio is generated once per playlist, so completed playlists survive a failure elsewhere; the Google backend chunks each summary to the API limit. The audio step warns and skips while the selected backend is not configured, so the text step can be used on its own.

The correction and TTS stages are opt-in: sources.jsonc enables them per playlist, and pipeline --correct / --audio enable them for every playlist for one run. When correction is present, summarize consumes its output.

PDF export

summarize-pdf renders the Markdown notes with reportlab: A4, print margins, a coloured heading hierarchy, hanging-indent bullets, inline code in a monospace face and a footer with the title and page number. It supports the subset the skill actually emits (headings, paragraphs, bullet/ordered lists, bold/italic, inline code, quotes, rules and code fences); tables and images are not rendered.

Paths may be files or directories (directories are scanned recursively, hidden files such as slides/.correct-reference.md are ignored). Fresh PDFs are skipped unless --force is given, and -o sets the destination for a single input. The flake wrapper sets PDF_FONT_DIR to the packaged DejaVu fonts; when running from source, point it at any directory containing DejaVuSans.ttf and DejaVuSans-Bold.ttf (DejaVu is required for Czech diacritics).

Spoken text and audio

The tts program prepares each summary for listening in two steps:

  1. Spoken text — the Convert-summary-to-tts skill rewrites the Markdown notes into continuous Czech prose: timestamps, heading markers, bullets, inline code and ellipses are removed, and points are joined with natural transitions. The result is written to summaries/tts/<base>.txt and uses the chat endpoint (tts.model overrides llm.model).
  2. Audio — summaries/audio/<base>.<ext> is produced from that text. The container is tts.audio_format (default wav; other containers are transcoded with ffmpeg).

The audio backend is selected with tts.backend in conf.jsonc:

"tts": {
  "backend": "omnivoice",  // default
  // "backend": "google"   // Google Cloud Text-to-Speech
}

OmniVoice backend

Voice design is controlled by tts.omnivoice.instruct; for example:

"tts": {
  "omnivoice": {
    "model": "k2-fsa/OmniVoice",
    "instruct": "male, moderate pitch",
    "language": "cs",
    "num_step": 32
  }
}

Further examples: female, low pitch, female, young adult, high pitch, male, elderly, low pitch, female, whisper (tts.omnivoice.speed is optional). Voice design was trained mainly on Chinese and English, so Czech results may vary; change the instruction if the voice is unstable.

OmniVoice enables denoise, reference-audio preprocessing and output postprocessing by default. This project keeps postprocessing disabled (tts.omnivoice.postprocess=false) so long lecture pauses are not removed; denoise and preprocess default to true.

The first user-level run downloads the model and tokenizer from Hugging Face into the user cache. The systemd service's cache under /var/lib/omnivoice is not reused.

The audio step calls omnivoice-infer-batch once per playlist, which loads the model once and writes that playlist's files before the next playlist starts. A completed playlist is therefore a checkpoint; a failure in one playlist does not discard audio already produced for the others, and the next run skips files newer than their spoken text. While tts.omnivoice.model is unset the CLI warns and skips the audio step; the text step is independent. tts.omnivoice.infer_batch overrides the executable path when it is not on PATH.

Omnivoice is not part of this flake: its installed build targets Python 3.13 with ROCm PyTorch, while the project uses Python 3.12. The adapter therefore uses the installed batch CLI, which calls the same OmniVoice Python API (OmniVoice.from_pretrained and model.generate) that its documented omnivoice package exposes. Direct in-process import would require moving the tts package to Python 3.13 and vendoring the omnivoice derivation and ROCm torch override.

Google Cloud TTS backend

Set tts.backend to "google". Credentials stay in .env or the real environment, in order of precedence:

  • GOOGLE_TTS_ACCESS_TOKEN — sent as Authorization: Bearer;
  • GOOGLE_TTS_API_KEY — sent as X-goog-api-key;
  • Application Default Credentials via google-auth (GOOGLE_APPLICATION_CREDENTIALS for a service-account JSON, or gcloud auth application-default login).

tts.google.project_id sets x-goog-user-project for access-token and ADC callers. It is omitted for API-key auth: the key already identifies its project, and sending the header with a key produces a serviceusage.services.use 403.

Czech voices include cs-CZ-Wavenet-B (female, default), cs-CZ-Standard-B (female), cs-CZ-Chirp3-HD-Charon (male) and cs-CZ-Chirp3-HD-Aoede (female). Configure them with tts.google.language, tts.google.voice, tts.google.gender, tts.google.speaking_rate, tts.google.pitch, tts.google.volume_gain_db, tts.google.sample_rate_hertz and tts.google.effects_profile. Chirp 3 HD voices ignore speaking rate and pitch; the backend omits those fields for them.

Gemini-TTS

Set tts.google.model to a Gemini model id to use Gemini-TTS through the same Cloud TTS endpoint:

"tts": {
  "google": {
    "model": "gemini-2.5-flash-tts",
    "voice": "Kore",
    "language": "cs-CZ",
    "prompt": "Mluv klidně a srozumitelně, jako přednášející."
  }
}

Available models are gemini-2.5-flash-tts, gemini-2.5-pro-tts, gemini-2.5-flash-lite-preview-tts (single-speaker) and gemini-3.1-flash-tts-preview. Gemini voices are bare names (Kore, Charon, Aoede, Puck, ...) rather than cs-CZ--prefixed voice ids; tts.google.voice defaults to Kore when a Gemini model is selected. The natural-language tts.google.prompt steers accent, pace, tone and emotion, so Gemini ignores tts.google.gender, tts.google.speaking_rate, tts.google.pitch, tts.google.volume_gain_db and tts.google.effects_profile; the backend omits those fields. Czech (cs-CZ) is available on Gemini-TTS at preview readiness. Gemini models are served from global, us, eu and northamerica-northeast1; gemini-3.1-flash-tts-preview is global-only. Use the regional endpoint form (<region>-texttospeech.googleapis.com) in tts.google.endpoint when the project requires a specific region.

Google limits a standard synchronous request to 5,000 bytes of input. The backend splits long spoken texts at paragraph, sentence and word boundaries into chunks of at most 4,800 UTF-8 bytes. Gemini requests are limited to 4,000 bytes of text, 4,000 bytes of prompt and 8,000 bytes combined, so their chunks are capped at 4,000 bytes minus the prompt size. In both cases the backend requests LINEAR16 WAV from Google, merges the chunks, and converts to tts.audio_format if needed. All requests use POST /v1/text:synthesize; tts.google.endpoint overrides the base URL. Google billing applies per request/character, unlike the local OmniVoice backend.

Pause tags and breath sounds

The .txt keeps the skill's canonical <short pause>, <long pause> and <breath> tags. They are not Cloud TTS syntax: the Google backend renders them as [short pause], [long pause] and [medium pause] for Gemini models, and removes them for standard/Chirp voices; OmniVoice removes them too. The .txt therefore stays portable.

Cloud TTS Gemini has no breath-frequency setting. Audible breaths come from the model, the voice, the style prompt and sentence boundaries. If they are distracting:

  • prefer a firm/clear voice (Kore, Orus, Iapetus) over Charon;
  • use a confident prompt with quiet breathing, for example "Clear, engaged lecture delivery, moderate pace, quiet breathing" instead of "calm", which can sound breathy;
  • avoid chains of short sentences: every full stop is a place where the model may inhale. The Convert-summary-to-tts skill therefore prefers longer prosodic phrases and uses short sentences only for emphasis.

<breath> is rendered as [medium pause], not as a breath sound. Cloud TTS has [sigh] and [uhm], but neither fits an informative lecture.

Development

nix develop
nix build .#pipeline                          # build all programs
nix run .#summarize -- --help
(cd scripts/transcribe && nix develop -c pytest)   # transcribe test suite
(cd scripts/tts && nix develop -c pytest)          # tts test suite

Skill prompts live in skills/; the nix wrappers point the LLM programs at them via PIPELINE_SKILLS_DIR.