Skip to content

Usage Examples

Jump to bottom
Tom Hindby edited this page Oct 31, 2025 · 4 revisions

Usage Examples

Below are common usage examples for NHK-TS. For a full list of options, run:

node dist/cli.js --help

Or with Docker:

docker run --rm -t ghcr.io/uppercenter/nhk-ts:latest --help

Most Common Workflow: Trim, Metadata Lookup, and Transcode

Process all .ts files in one directory, enrich with metadata, and transcode to MKV in a different output folder (default output is MKV unless --format mp4 is specified):

docker run --rm -t \
  -v /recordings:/input \
  -v /output:/output \
  -e TVDB_API_KEY=your_key \
  ghcr.io/uppercenter/nhk-ts:latest \
  --input /input \
  --output /output \
  --metadata \
  --transcode \
  --yes

Process All Recordings in a Directory

docker run --rm -t -v /recordings:/input -v /output:/output ghcr.io/uppercenter/nhk-ts:latest --input /input --output /output --yes

Process a Single File

docker run --rm -t -v /recordings:/input -v /output:/output ghcr.io/uppercenter/nhk-ts:latest --file /input/show.ts --output /output --yes

Enable Metadata Lookup (TVDB)

docker run --rm -t \
  -v /recordings:/input \
  -v /output:/output \
  -e TVDB_API_KEY=your_key \
  ghcr.io/uppercenter/nhk-ts:latest \
  --input /input \
  --output /output \
  --metadata \
  --yes

Transcode to MP4 with Custom Preset

docker run --rm -t -v /recordings:/input -v /output:/output ghcr.io/uppercenter/nhk-ts:latest --input /input --output /output --transcode --format mp4 --preset slow --crf 20 --yes

Use Hardware Acceleration (GPU)

NVIDIA GPU with Automatic Settings

docker run --rm -t --gpus all \
  -v /recordings:/input \
  -v /output:/output \
  ghcr.io/uppercenter/nhk-ts:latest \
  --input /input \
  --output /output \
  --transcode \
  --hw-accel nvenc \
  --best \
  --yes

Use Specific Hardware Encoder

docker run --rm -t --gpus all \
  -v /recordings:/input \
  -v /output:/output \
  ghcr.io/uppercenter/nhk-ts:latest \
  --input /input \
  --output /output \
  --transcode \
  --encoder hevc_nvenc \
  --preset medium \
  --crf 18 \
  --audio-copy \
  --yes

Auto-Detect Hardware Acceleration

docker run --rm -t --gpus all \
  -v /recordings:/input \
  -v /output:/output \
  ghcr.io/uppercenter/nhk-ts:latest \
  --input /input \
  --output /output \
  --transcode \
  --hw-accel auto \
  --best \
  --yes

Use a Different Reference Black/Logo Image

docker run --rm -t \
  -v /recordings:/input \
  -v /output:/output \
  -v /config:/config \
  ghcr.io/uppercenter/nhk-ts:latest \
  --input /input \
  --output /output \
  --reference /config/custom-image.png \
  --yes

Test Mode (No Trimming or Transcoding)

Analyse recordings without making any modifications:

docker run --rm -t -v /recordings:/input -v /output:/output ghcr.io/uppercenter/nhk-ts:latest --input /input --output /output --test --yes

Delete Originals After Processing

Delete original .ts and .nfo files only after all requested operations (metadata, trimming, transcoding) complete successfully:

docker run --rm -t -v /recordings:/input -v /output:/output ghcr.io/uppercenter/nhk-ts:latest --input /input --output /output --delete-original --yes

Increase Parallelism for Faster Processing

Process more frames in parallel (uses more CPU/RAM but is faster):

docker run --rm -t -v /recordings:/input -v /output:/output ghcr.io/uppercenter/nhk-ts:latest --input /input --output /output --parallelism 24 --yes

Use a Custom Metadata Cache Location

Persist metadata cache between runs by mounting a cache directory:

docker run --rm -t \
  -v /recordings:/input \
  -v /output:/output \
  -v /cache:/cache \
  -e TVDB_API_KEY=your_key \
  ghcr.io/uppercenter/nhk-ts:latest \
  --input /input \
  --output /output \
  --metadata \
  --metadata-cache /cache/metadata.json \
  --yes

Custom Start/End Window for Non-Standard Recordings

Adjust the analysis window for recordings with different programme transition timings:

docker run --rm -t -v /recordings:/input -v /output:/output ghcr.io/uppercenter/nhk-ts:latest \
  --input /input \
  --output /output \
  --start-window 100 \
  --end-window 230 \
  --yes

Custom Black Detection Thresholds

Fine-tune black frame detection sensitivity:

docker run --rm -t -v /recordings:/input -v /output:/output ghcr.io/uppercenter/nhk-ts:latest \
  --input /input \
  --output /output \
  --min-black 0.1 \
  --pix-threshold 0.15 \
  --yes

Copy Audio Streams Instead of Re-encoding

Preserve original audio quality by copying streams:

docker run --rm -t -v /recordings:/input -v /output:/output ghcr.io/uppercenter/nhk-ts:latest \
  --input /input \
  --output /output \
  --transcode \
  --audio-copy \
  --yes

Verbose Output for Debugging

Enable detailed logging:

docker run --rm -t -v /recordings:/input -v /output:/output ghcr.io/uppercenter/nhk-ts:latest \
  --input /input \
  --output /output \
  --verbosity verbose \
  --keep-debug \
  --yes

Complete Example: Full Workflow with Metadata, Transcoding, and GPU

A complete example combining metadata lookup, GPU transcoding, and cache persistence:

docker run --rm -t --gpus all \
  -v /recordings:/input \
  -v /output:/output \
  -v /cache:/cache \
  -e TVDB_API_KEY=your_key \
  ghcr.io/uppercenter/nhk-ts:latest \
  --input /input \
  --output /output \
  --metadata \
  --metadata-cache /cache/metadata.json \
  --transcode \
  --hw-accel auto \
  --best \
  --audio-copy \
  --format mkv \
  --yes

Clone this wiki locally