A Docker-based tool that converts .ts recordings to .mkv, preserves folder structure for series, and applies smart remux/encode decisions with hardware fallback.
- Docker (and Docker Compose)
- Continuous file monitoring (
watch,poll,once) - Resolution-aware encode parameters
- QSV-first encoding with fallback codec support
- SD force-encode and HEVC skip logic
- Remux fallback without subtitles when needed
- Parallel processing support
- Ntfy notifications
- Safety and regression checks via dedicated test scripts
- Configure docker-compose.yml:
- image pull from GHCR (default)
- input and output host mounts
- environment defaults grouped by category
- Adjust environment values directly in docker-compose.yml
- Start:
docker compose pull
docker compose up -dPrimary runtime config source: docker-compose.yml under environment.
Optional: mount and set TS_TO_MKV_CONFIG (or CONFIG_FILE) if you still want file-based config.
Important knobs:
MONITOR_MODE(watch,poll,once)MIN_FILE_AGE_SEC(a.tsis only processed after going this many seconds without being modified, so recordings still in progress are never converted or deleted; default300,0disables)WATCH_RESCAN_SEC(watch mode also rescans the input this often, catching deferred recordings and missed inotify events; default60)DELETE_TS,DELETE_SKIPPED_TS,DELETE_SKIPPED_VERIFY_DURATION,DELETE_SKIPPED_DURATION_TOLERANCE_PCT,DELETE_SKIPPED_DURATION_TOLERANCE_SECVIDEO_CODEC/FALLBACK_CODECUSE_CRF,CRF_*,BITRATE_*ENABLE_PARALLEL_PROCESSING,MAX_CONCURRENT_JOBSFORCE_ENCODE_SD,SKIP_ALREADY_HEVCDEINTERLACE,DEINTERLACE_MODE(send_framekeeps 25 fps,send_fielddoubles to 50 fps)MIN_FRAME_RATIO_PCT(encodes with fewer video frames than this share of duration × fps are rejected; default90)FLATTEN_NON_SERIES,SERIES_PATTERN
Output layout:
- Series recordings keep their input folder structure in the output. A recording counts as a series when its relative path matches
SERIES_PATTERN(default: anSxxExxepisode tag or aSeason/Staffeldirectory, matched case-insensitively). - All other recordings (movies) are written flat into the output root. Set
FLATTEN_NON_SERIES=falseto mirror the input structure for everything, as before.
Filename support note:
- Paths with spaces, quotes, and UTF-8 characters are supported.
- Paths containing literal newline characters are not supported.
Contributor setup, local validation commands, commit conventions, and release flow are documented in CONTRIBUTING.md.
A lightweight status dashboard is built into the container and starts automatically alongside the processor. Open http://<host>:8080 in a browser to see:
- Now processing — current file, elapsed time, live progress bar, speed, and ETA
- Queue — remaining files to process
- Completed — last 30 finished files
- Errors — any failed files
The default compose setup publishes dashboard port 8080 on the host as 8080. The container-side listen port can be changed with the WEB_PORT environment variable (remember to adjust the compose ports mapping accordingly).
The dashboard exposes a machine-readable endpoint at http://<host>:8080/api/status (on-demand, no auth; the dashboard JS polls it every 3 seconds). Useful for integrating with external tools:
Homepage (gethomepage.dev) custom API widget:
- ts2mkv:
icon: mdi-video-convert
href: http://your-host:8080
widget:
type: customapi
url: http://your-host:8080/api/status
refreshInterval: 5000
mappings:
- field: done_count
label: Done
- field: queue_remaining_count
label: Queued
- field: error_count
label: Errors
- field: current_progress_pct
label: Progress
suffix: "%"Home Assistant REST sensors:
sensor:
- platform: rest
name: ts2mkv_done
resource: http://your-host:8080/api/status
value_template: "{{ value_json.done_count }}"
scan_interval: 10
unit_of_measurement: files
- platform: rest
name: ts2mkv_queued
resource: http://your-host:8080/api/status
value_template: "{{ value_json.queue_remaining_count }}"
scan_interval: 10
unit_of_measurement: files
- platform: rest
name: ts2mkv_current_file
resource: http://your-host:8080/api/status
value_template: >-
{% if value_json.current %}
{{ value_json.current.display_path }}
{% else %}
idle
{% endif %}
scan_interval: 10
- platform: rest
name: ts2mkv_progress
resource: http://your-host:8080/api/status
value_template: >-
{{ value_json.current.progress_pct if value_json.current else 0 }}
scan_interval: 10
unit_of_measurement: "%"Runtime logs are written inside the container at /app/logs (configurable via LOG_DIR). Inspect them with docker compose exec ts2mkv ls /app/logs or via the web dashboard:
queue.log— files found by the startup scan (poll_queue.log— files found by the latest watch/poll rescan)done.log— successfully processed fileserror.log— failed filesffmpeg_encode_*.log— full ffmpeg output per encodeffmpeg_progress.<pid>.log/current_meta.<pid>.json— live per-job progress data consumed by the dashboard
This project is licensed under the EUPL 1.2 — see LICENSE for details.