{"id":21710158,"url":"https://github.com/dragongr/pymkv2mp4","last_synced_at":"2026-05-20T03:06:13.377Z","repository":{"id":257599693,"uuid":"858679108","full_name":"dragonGR/PyMKV2MP4","owner":"dragonGR","description":" Effortlessly convert MKV videos to MP4 format ","archived":false,"fork":false,"pushed_at":"2024-09-17T14:08:23.000Z","size":4,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-01-25T16:30:36.494Z","etag":null,"topics":["converter","mkv","mp4","python"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dragonGR.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-09-17T10:47:40.000Z","updated_at":"2024-09-17T14:08:27.000Z","dependencies_parsed_at":null,"dependency_job_id":"f2b0bd01-e48e-4e4e-9239-2960997af7e7","html_url":"https://github.com/dragonGR/PyMKV2MP4","commit_stats":null,"previous_names":["dragongr/pymkv2mp4"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dragonGR%2FPyMKV2MP4","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dragonGR%2FPyMKV2MP4/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dragonGR%2FPyMKV2MP4/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dragonGR%2FPyMKV2MP4/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dragonGR","download_url":"https://codeload.github.com/dragonGR/PyMKV2MP4/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244666423,"owners_count":20490286,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["converter","mkv","mp4","python"],"created_at":"2024-11-25T23:12:49.755Z","updated_at":"2026-05-20T03:06:13.365Z","avatar_url":"https://github.com/dragonGR.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# PyMKV2MP4\n\nA lightweight, zero-dependency Python CLI that converts MKV video files to MP4 format using **ffmpeg**. By default, both video and audio streams are **copied without re-encoding**, meaning the output is visually identical to the source and the conversion is near-instant.\n\nThis tool provides a reliable wrapper around ffmpeg with sensible defaults, robust error handling, and a clean command-line interface.\n\n---\n\n## Features\n\n*   **Lossless by Default**: Copies video and audio streams directly. No quality degradation, no waiting for re-encoding.\n*   **Smart Validation**: Checks for files, directories, and ffmpeg availability before execution.\n*   **Flexible Codecs**: Override the default `copy` behavior with any ffmpeg-supported video or audio codec.\n*   **Subtitle Control**: Copy, re-encode, or strip subtitle tracks entirely.\n*   **Dry-Run Mode**: Preview the exact ffmpeg command before executing it.\n*   **Overwrite Protection**: Prevents accidental data loss unless explicitly allowed with `-y`.\n*   **Portable**: Built with the Python standard library. No `pip install` required.\n\n---\n\n## Requirements\n\n| Dependency | Minimum Version | Notes |\n| :--- | :--- | :--- |\n| **Python** | 3.10+ | Uses modern union syntax (`|`) and `pathlib` |\n| **ffmpeg** | 4.4+ | Must be in system `PATH` or specified manually |\n\n### Checking your environment\n\n```bash\n# Verify Python\npython3 --version\n\n# Verify ffmpeg\nffmpeg -version | head -n 1\n```\n\nIf **ffmpeg** is missing, install it via your package manager:\n*   **Ubuntu/Debian**: `sudo apt install ffmpeg`\n*   **macOS**: `brew install ffmpeg`\n*   **Windows**: `winget install Gyan.FFmpeg`\n*   **Arch**: `sudo pacman -S ffmpeg`\n\n---\n\n## Installation \u0026 Usage\n\nJust clone the repository and run the script. No external Python packages are needed.\n\n```bash\ngit clone https://github.com/dragonGR/PyMKV2MP4.git\ncd PyMKV2MP4\n\n# Optional: make executable on Linux/macOS\nchmod +x main.py\n\n# Basic usage\npython main.py \u003cinput.mkv\u003e \u003coutput.mp4\u003e [options]\n```\n\n### Arguments\n\n| Argument | Description |\n| :--- | :--- |\n| `input` | Path to the source MKV file. |\n| `output` | Path where the MP4 file will be written. |\n\n### Optional Flags\n\n| Flag | Default | Description |\n| :--- | :--- | :--- |\n| `-v, --video-codec` | `copy` | Video codec to use. `copy` passes the stream through unchanged. |\n| `-a, --audio-codec` | `copy` | Audio codec to use. |\n| `-s, --subtitle-codec` | `copy` | Subtitle codec. Use `none` to remove subtitles. |\n| `-y, --overwrite` | `False` | Overwrite the output file if it already exists. |\n| `-n, --dry-run` | `False` | Print the generated ffmpeg command and exit. |\n| `--ffmpeg-path` | `None` | Full path to the ffmpeg binary if not in your PATH. |\n| `--verbose` | `False` | Enable debug-level logging. |\n| `--quiet` | `False` | Suppress ffmpeg progress output. |\n\n---\n\n## Common Use Cases\n\n### 1. Lossless Conversion (Default)\nThe fastest option. Video, audio, and subtitle streams are copied directly.\n```bash\npython main.py film.mkv film.mp4\n```\n\n### 2. Re-encode for Compatibility\nUse this if the source codecs are not MP4-compatible (e.g., MPEG-2 video or DTS audio).\n```bash\npython main.py film.mkv film.mp4 -v libx264 -a aac\n```\n\n### 3. Hardware Acceleration\nIf your hardware supports it, you can significantly speed up re-encoding:\n```bash\n# NVIDIA GPU\npython main.py film.mkv film.mp4 -v h264_nvenc\n\n# Apple Silicon\npython main.py film.mkv film.mp4 -v videotoolbox\n```\n\n### 4. Handling Subtitle Errors\nMany MKVs use **PGS** subtitles which aren't supported in MP4. Either strip them or convert them to text-based format:\n```bash\n# Strip subtitles\npython main.py film.mkv film.mp4 -s none\n\n# Convert to MP4-compatible text\npython main.py film.mkv film.mp4 -s mov_text\n```\n\n---\n\n## Supported Codecs (Examples)\n\n| Category | Codec | Description |\n| :--- | :--- | :--- |\n| **Video** | `copy` | Default. No quality loss, instant. |\n| | `libx264` | H.264 / AVC. High compatibility. |\n| | `libx265` | H.265 / HEVC. Better compression. |\n| **Audio** | `copy` | Direct stream copy. |\n| | `aac` | Standard for MP4. |\n| | `ac3` | Dolby Digital. Good for surround sound. |\n| **Subtitles**| `none` | Removes all subtitle tracks. |\n| | `mov_text` | Standard MP4 subtitle format. |\n\n---\n\n## Troubleshooting\n\n*   **\"Subtitle codec ... is not supported\"**: MP4 is stricter than MKV. Use `-s none` to remove them or `-s mov_text` to convert them.\n*   **File not found**: Ensure your paths are correct. If using Windows, wrap paths in quotes if they contain spaces.\n*   **Exit Code 1**: Check the output for error messages. This usually indicates a codec mismatch or a missing ffmpeg installation.\n*   **No Color**: If your terminal doesn't support ANSI colors, set the environment variable `NO_COLOR=1`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdragongr%2Fpymkv2mp4","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdragongr%2Fpymkv2mp4","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdragongr%2Fpymkv2mp4/lists"}