README
¶
skald
A media encoding suite built on ffmpeg, mkvtoolnix and friends.
skald wraps the tools you already use for video work and puts a measured, verifiable workflow around them — one that checks its own output and refuses to ship something wrong. The external tools stay yours to install and upgrade; skald orchestrates them and takes responsibility for the result.
What it does today
Dub transfer: move a foreign-language dub onto a better copy of the same film, without re-encoding anything.
You have two releases — a dual-audio one with the dub you want but mediocre video, and a high-quality one with only the original audio. skald measures how far apart their audio actually is, corrects for framerate drift, muxes the dub onto the good copy with mkvmerge, then re-measures its own output and throws it away if it doesn't line up.
It refuses more often than it succeeds, on purpose. A dub that came from a different edit cannot be fixed with a single offset, and shipping one that's four seconds out is worse than shipping nothing. That principle — measure, act, then verify the result independently — is the one every workflow added here is meant to follow.
Install
Homebrew (macOS, Linux)
brew install gettheforkoff/tap/skald
Pulls in ffmpeg, mkvtoolnix and mediainfo, installs the man page and completions, and strips the macOS quarantine attribute so there is no Gatekeeper warning.
Scoop (Windows)
scoop bucket add gettheforkoff https://github.com/gettheforkoff/scoop-bucket
scoop install skald
Install script
macOS and Linux — POSIX sh, so it behaves the same under bash, zsh and fish:
curl -fsSL https://raw.githubusercontent.com/gettheforkoff/skald/main/scripts/install.sh | sh
Pin a version or change the install directory:
curl -fsSL https://raw.githubusercontent.com/gettheforkoff/skald/main/scripts/install.sh | sh -s -- --version v1.0.0 --bindir ~/.local/bin
Windows (PowerShell):
irm https://raw.githubusercontent.com/gettheforkoff/skald/main/scripts/install.ps1 | iex
Both verify the SHA-256 checksum before installing.
Linux packages
.deb, .rpm, .apk and .pkg.tar.zst are on the
latest release.
From source
go install github.com/gettheforkoff/skald@latest
Manual download
Archives for macOS, Linux and Windows are on the releases page. macOS binaries are unsigned — Gatekeeper warns on first run unless you installed via Homebrew. Right-click → Open to bypass it.
Shell completions
Homebrew installs these for you. Otherwise, pick your shell:
bash
skald completion bash > /usr/local/etc/bash_completion.d/skald
zsh
skald completion zsh > "${fpath[1]}/_skald"
fish
skald completion fish > ~/.config/fish/completions/skald.fish
PowerShell
skald completion powershell | Out-String | Invoke-Expression
Add the PowerShell line to your $PROFILE to persist it.
External tools
skald shells out to ffmpeg, mkvmerge, mediainfo and Sushi.Net. Run
skald doctor to see which are present and how to install the rest.
Usage
Interactive — asks about anything it can't work out on its own:
skald dub --dub dual-audio.mkv --target remux.mkv
Unattended — every decision answered up front, safe for scripts:
skald dub --dub dual-audio.mkv --target remux.mkv \
--dub-language por --on-drift=correct --on-partial-dub=warn \
--yes --no-input
Batch: save a plan, review it, run it later.
skald dub --dub dual-audio.mkv --target remux.mkv --save-plan jobs.yaml
skald apply jobs.yaml --dry-run
skald apply jobs.yaml --yes
Answer one question without transferring anything:
skald check match --dub a.mkv --target b.mkv # same edit?
skald check delay --dub a.mkv --target b.mkv # how far apart, and steady?
skald check drift --dub a.mkv --target b.mkv # is it a framerate mismatch?
skald check dub --dub a.mkv --target b.mkv # is the dub complete?
Every finding carries a code. To find out what one means:
skald explain delay-drifts
Output
Findings go to stdout; progress and prompts go to stderr, so you can redirect
one without losing the other. -v adds the numbers behind each finding, -vv
adds the ffmpeg and mkvmerge command lines. --json emits the whole event
stream as one document, and --plain gives tab-separated lines for grep.
Exit codes: 0 done · 1 failed · 2 bad usage · 3 missing tool ·
4 stopped on a decision · 5 needed input it couldn't ask for ·
6 output exists · 130 interrupted.
Documentation
docs/workflows.org— which command to reach fordocs/howto-rate-correction.org— drifting dubsdocs/howto-partial-dub.org— incomplete dubsdocs/rate-calibration.organddocs/dubcheck-calibration.org— the measurements the thresholds are based on. Read these before changing a threshold.
Project status
Working and in use, pre-1.0. The command surface may still change.
Per-track selection and renaming (--keep-audio, --keep-subs, --dub-audio,
--dub-subs, --name, --lang) are wired into the mux. The interactive
prompts have had little real-world use.
Contributing
mise run test
mise run lint # must stay at zero findings
Conventional commits. Toolchain versions come from mise.toml — use
mise run <task> rather than calling go or golangci-lint directly.
License
Documentation
¶
There is no documentation for this package.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
internal
|
|
|
cli
Package cli wires together the skald command-line interface using cobra, defining commands, flags, and dispatching to the underlying packages.
|
Package cli wires together the skald command-line interface using cobra, defining commands, flags, and dispatching to the underlying packages. |
|
command
Package command provides an exec.Cmd-as-data builder and runner, allowing external commands to be constructed, inspected, and executed in a testable way.
|
Package command provides an exec.Cmd-as-data builder and runner, allowing external commands to be constructed, inspected, and executed in a testable way. |
|
config
Package config manages skald's configuration via viper, including default values and configuration file loading.
|
Package config manages skald's configuration via viper, including default values and configuration file loading. |
|
correlate
Package correlate implements pure-Go cross-correlation of audio signals to determine time offsets between tracks.
|
Package correlate implements pure-Go cross-correlation of audio signals to determine time offsets between tracks. |
|
diag
Package diag is skald's de-jargoning enforcement mechanism: every user-facing outcome gets a stable slug Code, a plain-language Title and Short summary, a longer Explain page, and concrete Actions.
|
Package diag is skald's de-jargoning enforcement mechanism: every user-facing outcome gets a stable slug Code, a plain-language Title and Short summary, a longer Explain page, and concrete Actions. |
|
dubtransfer
Package dubtransfer implements the core validate, measure, mux, sync, and run logic for transferring foreign-language audio dubs between media files.
|
Package dubtransfer implements the core validate, measure, mux, sync, and run logic for transferring foreign-language audio dubs between media files. |
|
ios
Package ios bundles the input, output, and error streams a command uses into a single injected struct, so that terminal and mode decisions are made in one place and commands never touch os.Stdout directly.
|
Package ios bundles the input, output, and error streams a command uses into a single injected struct, so that terminal and mode decisions are made in one place and commands never touch os.Stdout directly. |
|
job
Package job holds skald's job platform: the exit-code taxonomy shared by every command, the Job and Runner types and event stream every job emits, and — in later tasks — the engine that drives dub, apply, and check jobs through that stream.
|
Package job holds skald's job platform: the exit-code taxonomy shared by every command, the Job and Runner types and event stream every job emits, and — in later tasks — the engine that drives dub, apply, and check jobs through that stream. |
|
jobs/dub
Package dub adapts the dubtransfer domain pipeline onto the job engine.
|
Package dub adapts the dubtransfer domain pipeline onto the job engine. |
|
mediainfo
Package mediainfo parses ffprobe JSON output and tracker text into a structured Media model describing a file's streams and metadata.
|
Package mediainfo parses ffprobe JSON output and tracker text into a structured Media model describing a file's streams and metadata. |
|
plan
Package plan defines skald's plan file: the v1 YAML contract that lets a dub job be fully described outside of an interactive session.
|
Package plan defines skald's plan file: the v1 YAML contract that lets a dub job be fully described outside of an interactive session. |
|
probe
Package probe wraps ffprobe and ffmpeg invocations against real media files, exposing their results for downstream analysis.
|
Package probe wraps ffprobe and ffmpeg invocations against real media files, exposing their results for downstream analysis. |
|
prompt
Package prompt is the interface through which every interactive question skald asks is asked, so that the job engine can resolve human decisions without depending on a real terminal.
|
Package prompt is the interface through which every interactive question skald asks is asked, so that the job engine can resolve human decisions without depending on a real terminal. |
|
tools
Package tools discovers external binaries (such as ffmpeg and ffprobe) required by skald on the host system.
|
Package tools discovers external binaries (such as ffmpeg and ffprobe) required by skald on the host system. |
|
ui/jsonout
Package jsonout renders a job.Event stream as one JSON document.
|
Package jsonout renders a job.Event stream as one JSON document. |
|
ui/text
Package text renders a job.Event stream as human-readable text.
|
Package text renders a job.Event stream as human-readable text. |
|
ui/uievents
Package uievents holds one canned job.Event stream, shared by every renderer's tests.
|
Package uievents holds one canned job.Event stream, shared by every renderer's tests. |