91 lines
4.2 KiB
Markdown
91 lines
4.2 KiB
Markdown
# Usage
|
|
|
|
PolyScribe is a command-line tool. Run `polyscribe -h` at any time to see the latest help.
|
|
|
|
Common patterns
|
|
- Single file to transcript (JSON + SRT):
|
|
- polyscribe -o output path/to/audio_or_video.mp3
|
|
- Multiple files → merged transcript:
|
|
- polyscribe -m -o output merged path/a.mp3 path/b.mp4
|
|
- Multiple files → both merged and separate outputs:
|
|
- polyscribe --merge-and-separate -o output path/a.json path/b.json
|
|
- Prompt for speaker names per input:
|
|
- polyscribe --set-speaker-names -o output path/a.mp3 path/b.mp4
|
|
|
|
CLI reference
|
|
- Positional arguments:
|
|
- inputs: One or more .json transcripts or media files (audio/video). When media files are given, PolyScribe extracts audio via ffmpeg.
|
|
- Flags:
|
|
- -o, --output FILE_OR_DIR
|
|
- Output base path. For directories, date prefix is added and both .json and .srt are created. If omitted, JSON prints to stdout.
|
|
- -m, --merge
|
|
- Merge all inputs into a single output instead of one output per input.
|
|
- --merge-and-separate
|
|
- Write both a merged output and separate outputs (requires -o directory).
|
|
- --set-speaker-names
|
|
- Prompt for a speaker label per input (useful for multi-speaker datasets).
|
|
- --language LANG
|
|
- Language hint (e.g., en, de). English-only models reject non-en hints.
|
|
- --gpu-backend [auto|cpu|cuda|hip|vulkan]
|
|
- Choose runtime backend. Default is auto (prefers CUDA → HIP → Vulkan → CPU), depending on detection.
|
|
- --gpu-layers N
|
|
- Number of layers to offload to the GPU when supported.
|
|
- models download
|
|
- Launch interactive model downloader (lists Hugging Face models; multi-select to download).
|
|
- Controls: Use Up/Down to navigate, Space to toggle selections, and Enter to confirm. Models are grouped by base (e.g., tiny, base, small).
|
|
- models update
|
|
- Verify/update local models by comparing sizes and hashes with the upstream manifest.
|
|
- -v, --verbose (repeatable)
|
|
- Increase log verbosity; use -vv for very detailed logs.
|
|
- -q, --quiet
|
|
- Suppress non-error logs to stderr; does not affect stdout outputs.
|
|
- --no-interaction
|
|
- Disable all interactive prompts (for CI). Combine with env vars to control behavior.
|
|
- Subcommands:
|
|
- models download: Launch interactive model downloader.
|
|
- models update: Verify/update local models (non-interactive).
|
|
- plugins list|info|run: Discover and run plugins.
|
|
- completions <shell>: Write shell completion script to stdout.
|
|
- man: Write a man page to stdout.
|
|
|
|
Expected outputs
|
|
- For each processed input or merged group, PolyScribe produces:
|
|
- A JSON transcript file with segments (id, speaker, start, end, text).
|
|
- An SRT subtitle file with timestamps and text (speaker: prefixed when provided).
|
|
- When -o is used with a directory, outputs are written into that directory with a YYYY-MM-DD prefix.
|
|
|
|
Typical workflows
|
|
1) Single file → transcript:
|
|
- polyscribe -o output media/example.mp3
|
|
|
|
2) Multiple files → merged transcript:
|
|
- polyscribe -m -o output merged media/a.mp3 media/b.mp4 media/c.wav
|
|
|
|
3) Multiple files → both merged and individual transcripts:
|
|
- polyscribe --merge-and-separate -o output media/a.json media/b.json
|
|
|
|
4) Video → extract audio automatically:
|
|
- polyscribe -o output videos/talk.mp4
|
|
(Requires ffmpeg on PATH.)
|
|
|
|
Model locations
|
|
- Development builds (debug): ./models is used by default.
|
|
- Packaged releases: $XDG_DATA_HOME/polyscribe/models or ~/.local/share/polyscribe/models.
|
|
- Override:
|
|
- POLYSCRIBE_MODELS_DIR=/path/to/models
|
|
- WHISPER_MODEL=/path/to/specific_model.bin (forces exact model file).
|
|
|
|
Environment variables
|
|
- POLYSCRIBE_MODELS_DIR: Override default models directory.
|
|
- WHISPER_MODEL: Point directly to a model file.
|
|
- XDG_DATA_HOME/HOME: Used to resolve default model path for release builds.
|
|
- CI/GITHUB_ACTIONS: When set, PolyScribe assumes non-TTY in some paths and may avoid prompts.
|
|
- Test-only toggles (used by our tests; not recommended in production):
|
|
- POLYSCRIBE_TEST_FORCE_CUDA=1
|
|
- POLYSCRIBE_TEST_FORCE_HIP=1
|
|
- POLYSCRIBE_TEST_FORCE_VULKAN=1
|
|
|
|
Notes
|
|
- GPU selection depends on both build features and runtime detection. Build with the corresponding cargo features (see development.md) for CUDA/HIP/Vulkan support.
|
|
- English-only models cannot be used with non-English language hints.
|