- Python 97.8%
- Nix 1.4%
- Dockerfile 0.4%
- Shell 0.4%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
| docker | ||
| scripts | ||
| skills | ||
| .dockerignore | ||
| .env.example | ||
| .envrc | ||
| .gitignore | ||
| AGENTS.md | ||
| compose.env.example | ||
| conf.example.jsonc | ||
| docker-compose.yaml | ||
| Dockerfile | ||
| flake.lock | ||
| flake.nix | ||
| README.md | ||
| sources.example.jsonc | ||
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
-
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/.envIn
conf.jsonc, setpipeline.content_dir(absolute is recommended for cron), the endpoints and models:transcribe.base_url/transcribe.model(OpenAI-compatible/audio/transcriptionsendpoint);llm.base_url/llm.model(chat-completions endpoint used bycorrect-transcript,summarizeandtts).
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 overrideconf.jsoncfor one-off runs, and every program accepts--config PATH.PIPELINE_CONFIG_DIRorpipeline --config-dir PATHselects a different directory. -
List playlists in
sources.jsonc. The label becomes the content folder name. Options use the same names as the legacylinks.mdflags:Option Effect renameCanonical lecture names; prezentaceitems are skippedcorrectRun LLM correction for this playlist pdfAlso export PDF notes for this playlist audioRun 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": falseon an entry to keep it without downloading it. A legacylinks.md(label: url | option ...) is still accepted when nosources.jsoncexists;--sourcesselects a file explicitly.download,transcribeandsummarizealways run. A playlist without options still gets transcripts and notes; the optional stages apply only where listed.pipeline --correct,--pdfand--audioenable 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 pipelinefrom the profile) soPIPELINE_SKILLS_DIRand the child tools are onPATH. Do not rely onnix developin cron. HOMEmust belong to the user that owns the configuration and content directories. Prefer absolute paths inconf.jsoncforpipeline.content_dirandtts.omnivoice.infer_batch.- Exit status:
0success or lock skip,1one or more stage failures,2configuration/source errors. Cron mails the output whenMAILTOis set. - Keep
.envandconf.jsoncreadable 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.
-
Prepare
~/.config/lecture-compressoras described in Setup. -
Copy
compose.env.exampletocompose.envand set absolute paths and the cron schedule:cp compose.env.example compose.env $EDITOR compose.envPIPELINE_CRONuses 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, defaultUTC); the image includes timezone data. -
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.lockthere. - The container runs as root by default, so generated files on the host
are root-owned. Uncomment
user:indocker-compose.yaml, setPUID/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.backendtogoogle(credentials in the mounted.env), or mount a workingomnivoice-infer-batchand pointtts.omnivoice.infer_batchat its container path. GOOGLE_APPLICATION_CREDENTIALSand other credential files must be mounted into the container and referenced by their container path in.env.- Container logs use Docker's
json-filedriver with 10 MB × 3 rotation; adjust theloggingblock indocker-compose.yamlfor 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/andsummaries/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| renameadditionally skip presentation recordings and rename new lectures canonically (see above). - transcribe runs only for videos with no subtitle sidecar at
all (a YouTube
.cs.srtcounts as present, so no redundant Whisper calls). - correct writes
<base>.corrected.srtand skips it when it is newer than the source. - summarize prefers the corrected subtitle, otherwise
.cs.srt, otherwise.srt, and writessummaries/<base>.md(skipped when newer than the input). With thepdfoption it also writessummaries/<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 (--forceoverrides). - tts rewrites each notes file to
summaries/tts/<base>.txt(skipped while newer than the notes) and synthesizessummaries/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:
- Spoken text — the
Convert-summary-to-ttsskill 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 tosummaries/tts/<base>.txtand uses the chat endpoint (tts.modeloverridesllm.model). - Audio —
summaries/audio/<base>.<ext>is produced from that text. The container istts.audio_format(defaultwav; 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 asAuthorization: Bearer;GOOGLE_TTS_API_KEY— sent asX-goog-api-key;- Application Default Credentials via
google-auth(GOOGLE_APPLICATION_CREDENTIALSfor a service-account JSON, orgcloud 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) overCharon; - 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-ttsskill 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.