# Play DV on Windows
Converts 4K Dolby Vision MKV files to MP4 format while preserving DV metadata and extracting subtitles. Designed for Windows users who need MP4 files for proper Dolby Vision playback in Windows Media Player.
## Why This Exists
Windows Dolby Vision playback is limited. While both MKV and MP4 can contain DV metadata, Windows Media Player only properly handles DV in MP4 containers. This tool converts your MKV files to MP4 without re-encoding, preserving quality and DV metadata while making them compatible with Windows DV playback.
Additionally, it extracts embedded subtitles to external SRT files, which is often necessary for proper subtitle display in Windows Media Player.
## Who This Is For
- Windows users with Dolby Vision displays (OLED TVs, monitors)
- People who download 4K DV content in MKV format
- Anyone wanting automated conversion through qBittorrent
- Users who need reliable subtitle extraction
## Features
- Preserves Dolby Vision metadata during conversion
- No re-encoding (fast, lossless quality)
- Extracts English subtitles to SRT files
- **Smart subtitle handling**: Extracts compatible text-based subtitles, warns about incompatible PGS/image formats
- Automatic detection of 4K DV content
- qBittorrent integration for automated processing
- Handles both movies and TV show episodes
- Configurable output organization
## Installation
**Requirements:**
- Python 3.7+
- FFmpeg with ffprobe (must be installed separately)
- qBittorrent (optional, for automation)
### Quick Installation (Recommended)
```bash
pip install play-dv-on-windows
play-dv-setup
```
### Development Installation
```bash
git clone https://github.com/anfen93/play-dv-on-windows.git
cd play-dv-on-windows
pip install -e .
play-dv-setup
```
## Usage
### Command Line Interface
After installation, you have access to these commands:
**Setup and Configuration:**
```bash
play-dv-setup # Initial setup and dependency checking
play-dv-config --init # Initialize configuration
play-dv-config --show # Show current configuration
play-dv-config --validate # Validate configuration
```
**Convert files directly:**
```bash
play-dv-convert movie.mkv # Convert single file
play-dv-convert file1.mkv file2.mkv # Convert multiple files
play-dv-convert movie.mkv --output-dir /tmp/output # Specify output directory
play-dv-convert movie.mkv --dry-run # See what would be done
play-dv-convert movie.mkv --config custom.json # Use custom config
```
> **⚠️ Important Security Note**: Before converting files, you must configure allowed source directories. The tool will reject files outside of these directories for security. See the Configuration section below for setup details.
**qBittorrent automation:**
1. Enable Web UI in qBittorrent
2. Configure credentials: `play-dv-config --init` then edit `config/local.json`
3. Set post-execution script: `play-dv-qbt "%N" "%F" "%I"`
The script automatically detects 4K Dolby Vision content by analyzing torrent names for keywords like "2160p", "4K", "DV", "DoVi", etc.
## Configuration
### ⚠️ Required First Step: Configure Allowed Directories
For security, the tool only processes files from explicitly allowed directories. **You must configure this before converting any files:**
1. **Initialize configuration:**
```bash
play-dv-config --init
```
2. **Edit your config file** (`C:\Users\USERNAME\.play-dv-on-windows\local.json` on Windows):
```bash
# Windows
notepad "C:\Users\%USERNAME%\.play-dv-on-windows\local.json"
# Or use any editor
code "C:\Users\%USERNAME%\.play-dv-on-windows\local.json"
```
3. **Add your source directories:**
```json
{
"paths": {
"allowed_base_dirs": [
"C:\\torrents",
"C:\\Downloads",
"D:\\Media"
]
}
}
```
4. **Validate your config:**
```bash
play-dv-config --validate
```
If you try to convert files from directories not in `allowed_base_dirs`, you'll get an error like:
```
ERROR - Invalid input file: File path not in allowed directory
```
### Full Configuration Options
The tool uses a layered configuration system. Your `local.json` can contain:
```json
{
"paths": {
"output_dir": "./converted",
"log_dir": "./logs",
"allowed_base_dirs": [".", "~", "/path/to/downloads"]
},
"processing": {
"delete_after_success": false,
"max_parallel_episodes": 2
},
"filters": {
"require_4k": true,
"require_dv": true
},
"qbittorrent": {
"enabled": true,
"host": "localhost",
"port": 8080,
"username": "admin",
"password": "your_password"
}
}
```
Environment variables are also supported via `.env` file:
```bash
QBT_HOST=localhost
QBT_PORT=8080
QBT_USERNAME=admin
QBT_PASSWORD=your_password
```
## How It Works
**Detection:** Analyzes torrent names for 4K and Dolby Vision indicators
**Conversion:** Uses FFmpeg to remux streams without re-encoding
**Organization:** Creates clean folder structures for media libraries
**Cleanup:** Optionally removes source files after successful conversion
The conversion process:
1. Analyze MKV streams with ffprobe
2. Select video stream, ALL audio streams, and compatible subtitle streams
3. Extract text-based subtitles to separate SRT files (SRT, ASS, MOV_TEXT only)
4. Remux selected streams to MP4 container with Windows Media Player compatible audio conversion
5. Preserve all metadata including Dolby Vision
## Audio & Subtitle Handling
### Audio Processing
- **Includes ALL audio streams** from source (not just English)
- **Automatic conversion** of incompatible formats (DTS, TrueHD, PCM) to EAC3 for Windows Media Player compatibility
- **Preserves compatible formats** (EAC3, AC3, AAC) without re-encoding
### Subtitle Processing
- **Text-based subtitles** (SRT, ASS, MOV_TEXT): Direct extraction to external SRT files
- **Image-based subtitles** (PGS, DVD): Shows warning and skips (not compatible with Windows Media Player)
- **Conversion continues** even if some subtitle extraction fails
**Note**: For PGS/image subtitle conversion, use Subtitle Edit (free software): https://www.nikse.dk/subtitleedit
## Testing
```bash
python run_tests.py all # Full test suite
python run_tests.py quick # Quick validation
python run_tests.py convert # Core conversion tests
python run_tests.py qbt # qBittorrent integration tests
```
## Project Structure
```
src/play_dv_on_windows/
├── convert.py # Core MKV to MP4 conversion
├── qbt_post_process.py # qBittorrent post-execution handler
├── config_manager.py # Configuration management
├── cli.py # Command-line interface
└── config/ # Package configuration files
config/ # User configuration directory
└── local.json # User configuration overrides
tests/ # Comprehensive test suite
docs/ # Additional documentation
```
## Technical Details
- Uses stream copying (`-c:v copy`, `-c:a copy`) for lossless conversion
- Preserves Dolby Vision RPU and metadata
- Supports multiple subtitle tracks
- Handles both single files and batch processing
- Thread-safe parallel processing for TV episodes
- Comprehensive error handling and logging
## Troubleshooting
**"File path not in allowed directory" error:** Add your source directory to `allowed_base_dirs` in your config file. See Configuration section above.
**FFmpeg not found:** Install FFmpeg and ensure it's in system PATH
**Conversion fails:** Check logs in `logs/` directory for detailed error information
**qBittorrent issues:** Verify Web UI is enabled and credentials are correct
**No files processed:** Ensure content matches 4K DV detection criteria
**Config file not found:** Run `play-dv-config --init` to create the initial configuration
## Development
**Setup for development:**
```bash
git clone https://github.com/anfen93/play-dv-on-windows.git
cd play-dv-on-windows
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -e .
pip install -r requirements-test.txt
pre-commit install
```
## Contributing
1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass
5. Submit a pull request
## License
MIT License - see LICENSE file for details.
---
A practical solution for Windows Dolby Vision compatibility issues.
Raw data
{
"_id": null,
"home_page": null,
"name": "play-dv-on-windows",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "dolby-vision, mkv, mp4, converter, qbittorrent, 4k",
"author": null,
"author_email": "anfen <anfen93@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/26/25/61fff1f7b239bef0c0ce0cee184872f4bc47702fde8e7ec9a77ce1bb174e/play_dv_on_windows-1.0.13.tar.gz",
"platform": null,
"description": "# Play DV on Windows\n\nConverts 4K Dolby Vision MKV files to MP4 format while preserving DV metadata and extracting subtitles. Designed for Windows users who need MP4 files for proper Dolby Vision playback in Windows Media Player.\n\n## Why This Exists\n\nWindows Dolby Vision playback is limited. While both MKV and MP4 can contain DV metadata, Windows Media Player only properly handles DV in MP4 containers. This tool converts your MKV files to MP4 without re-encoding, preserving quality and DV metadata while making them compatible with Windows DV playback.\n\nAdditionally, it extracts embedded subtitles to external SRT files, which is often necessary for proper subtitle display in Windows Media Player.\n\n## Who This Is For\n\n- Windows users with Dolby Vision displays (OLED TVs, monitors)\n- People who download 4K DV content in MKV format\n- Anyone wanting automated conversion through qBittorrent\n- Users who need reliable subtitle extraction\n\n## Features\n\n- Preserves Dolby Vision metadata during conversion\n- No re-encoding (fast, lossless quality)\n- Extracts English subtitles to SRT files\n- **Smart subtitle handling**: Extracts compatible text-based subtitles, warns about incompatible PGS/image formats\n- Automatic detection of 4K DV content\n- qBittorrent integration for automated processing\n- Handles both movies and TV show episodes\n- Configurable output organization\n\n## Installation\n\n**Requirements:**\n- Python 3.7+\n- FFmpeg with ffprobe (must be installed separately)\n- qBittorrent (optional, for automation)\n\n### Quick Installation (Recommended)\n\n```bash\npip install play-dv-on-windows\nplay-dv-setup\n```\n\n### Development Installation\n\n```bash\ngit clone https://github.com/anfen93/play-dv-on-windows.git\ncd play-dv-on-windows\npip install -e .\nplay-dv-setup\n```\n\n## Usage\n\n### Command Line Interface\n\nAfter installation, you have access to these commands:\n\n**Setup and Configuration:**\n```bash\nplay-dv-setup # Initial setup and dependency checking\nplay-dv-config --init # Initialize configuration\nplay-dv-config --show # Show current configuration\nplay-dv-config --validate # Validate configuration\n```\n\n**Convert files directly:**\n```bash\nplay-dv-convert movie.mkv # Convert single file\nplay-dv-convert file1.mkv file2.mkv # Convert multiple files\nplay-dv-convert movie.mkv --output-dir /tmp/output # Specify output directory\nplay-dv-convert movie.mkv --dry-run # See what would be done\nplay-dv-convert movie.mkv --config custom.json # Use custom config\n```\n\n> **\u26a0\ufe0f Important Security Note**: Before converting files, you must configure allowed source directories. The tool will reject files outside of these directories for security. See the Configuration section below for setup details.\n\n**qBittorrent automation:**\n1. Enable Web UI in qBittorrent\n2. Configure credentials: `play-dv-config --init` then edit `config/local.json`\n3. Set post-execution script: `play-dv-qbt \"%N\" \"%F\" \"%I\"`\n\nThe script automatically detects 4K Dolby Vision content by analyzing torrent names for keywords like \"2160p\", \"4K\", \"DV\", \"DoVi\", etc.\n\n## Configuration\n\n### \u26a0\ufe0f Required First Step: Configure Allowed Directories\n\nFor security, the tool only processes files from explicitly allowed directories. **You must configure this before converting any files:**\n\n1. **Initialize configuration:**\n ```bash\n play-dv-config --init\n ```\n\n2. **Edit your config file** (`C:\\Users\\USERNAME\\.play-dv-on-windows\\local.json` on Windows):\n ```bash\n # Windows\n notepad \"C:\\Users\\%USERNAME%\\.play-dv-on-windows\\local.json\"\n\n # Or use any editor\n code \"C:\\Users\\%USERNAME%\\.play-dv-on-windows\\local.json\"\n ```\n\n3. **Add your source directories:**\n ```json\n {\n \"paths\": {\n \"allowed_base_dirs\": [\n \"C:\\\\torrents\",\n \"C:\\\\Downloads\",\n \"D:\\\\Media\"\n ]\n }\n }\n ```\n\n4. **Validate your config:**\n ```bash\n play-dv-config --validate\n ```\n\nIf you try to convert files from directories not in `allowed_base_dirs`, you'll get an error like:\n```\nERROR - Invalid input file: File path not in allowed directory\n```\n\n### Full Configuration Options\n\nThe tool uses a layered configuration system. Your `local.json` can contain:\n\n```json\n{\n \"paths\": {\n \"output_dir\": \"./converted\",\n \"log_dir\": \"./logs\",\n \"allowed_base_dirs\": [\".\", \"~\", \"/path/to/downloads\"]\n },\n \"processing\": {\n \"delete_after_success\": false,\n \"max_parallel_episodes\": 2\n },\n \"filters\": {\n \"require_4k\": true,\n \"require_dv\": true\n },\n \"qbittorrent\": {\n \"enabled\": true,\n \"host\": \"localhost\",\n \"port\": 8080,\n \"username\": \"admin\",\n \"password\": \"your_password\"\n }\n}\n```\n\nEnvironment variables are also supported via `.env` file:\n```bash\nQBT_HOST=localhost\nQBT_PORT=8080\nQBT_USERNAME=admin\nQBT_PASSWORD=your_password\n```\n\n## How It Works\n\n**Detection:** Analyzes torrent names for 4K and Dolby Vision indicators\n**Conversion:** Uses FFmpeg to remux streams without re-encoding\n**Organization:** Creates clean folder structures for media libraries\n**Cleanup:** Optionally removes source files after successful conversion\n\nThe conversion process:\n1. Analyze MKV streams with ffprobe\n2. Select video stream, ALL audio streams, and compatible subtitle streams\n3. Extract text-based subtitles to separate SRT files (SRT, ASS, MOV_TEXT only)\n4. Remux selected streams to MP4 container with Windows Media Player compatible audio conversion\n5. Preserve all metadata including Dolby Vision\n\n## Audio & Subtitle Handling\n\n### Audio Processing\n- **Includes ALL audio streams** from source (not just English)\n- **Automatic conversion** of incompatible formats (DTS, TrueHD, PCM) to EAC3 for Windows Media Player compatibility\n- **Preserves compatible formats** (EAC3, AC3, AAC) without re-encoding\n\n### Subtitle Processing\n- **Text-based subtitles** (SRT, ASS, MOV_TEXT): Direct extraction to external SRT files\n- **Image-based subtitles** (PGS, DVD): Shows warning and skips (not compatible with Windows Media Player)\n- **Conversion continues** even if some subtitle extraction fails\n\n**Note**: For PGS/image subtitle conversion, use Subtitle Edit (free software): https://www.nikse.dk/subtitleedit\n\n## Testing\n\n```bash\npython run_tests.py all # Full test suite\npython run_tests.py quick # Quick validation\npython run_tests.py convert # Core conversion tests\npython run_tests.py qbt # qBittorrent integration tests\n```\n\n## Project Structure\n\n```\nsrc/play_dv_on_windows/\n\u251c\u2500\u2500 convert.py # Core MKV to MP4 conversion\n\u251c\u2500\u2500 qbt_post_process.py # qBittorrent post-execution handler\n\u251c\u2500\u2500 config_manager.py # Configuration management\n\u251c\u2500\u2500 cli.py # Command-line interface\n\u2514\u2500\u2500 config/ # Package configuration files\n\nconfig/ # User configuration directory\n\u2514\u2500\u2500 local.json # User configuration overrides\n\ntests/ # Comprehensive test suite\ndocs/ # Additional documentation\n```\n\n## Technical Details\n\n- Uses stream copying (`-c:v copy`, `-c:a copy`) for lossless conversion\n- Preserves Dolby Vision RPU and metadata\n- Supports multiple subtitle tracks\n- Handles both single files and batch processing\n- Thread-safe parallel processing for TV episodes\n- Comprehensive error handling and logging\n\n## Troubleshooting\n\n**\"File path not in allowed directory\" error:** Add your source directory to `allowed_base_dirs` in your config file. See Configuration section above.\n\n**FFmpeg not found:** Install FFmpeg and ensure it's in system PATH\n\n**Conversion fails:** Check logs in `logs/` directory for detailed error information\n\n**qBittorrent issues:** Verify Web UI is enabled and credentials are correct\n\n**No files processed:** Ensure content matches 4K DV detection criteria\n\n**Config file not found:** Run `play-dv-config --init` to create the initial configuration\n\n## Development\n\n**Setup for development:**\n```bash\ngit clone https://github.com/anfen93/play-dv-on-windows.git\ncd play-dv-on-windows\npython -m venv .venv\nsource .venv/bin/activate # Windows: .venv\\Scripts\\activate\npip install -e .\npip install -r requirements-test.txt\npre-commit install\n```\n\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Add tests for new functionality\n4. Ensure all tests pass\n5. Submit a pull request\n\n## License\n\nMIT License - see LICENSE file for details.\n\n---\n\nA practical solution for Windows Dolby Vision compatibility issues.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A comprehensive 4K Dolby Vision MKV to MP4 converter with qBittorrent integration",
"version": "1.0.13",
"project_urls": {
"Documentation": "https://github.com/anfen93/play-dv-on-windows/docs",
"Homepage": "https://github.com/anfen93/play-dv-on-windows",
"Issues": "https://github.com/anfen93/play-dv-on-windows/issues",
"Repository": "https://github.com/anfen93/play-dv-on-windows"
},
"split_keywords": [
"dolby-vision",
" mkv",
" mp4",
" converter",
" qbittorrent",
" 4k"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "99e9344d9dce8180f6409b613c3c96d7bb7fac7f0c2c36b8ca10bae2bea87d59",
"md5": "e4d4965ce0e9444e2a3e72343f2069f5",
"sha256": "bfb214adddfb74e0445edf626bca652a78d54b5622f7db18e68d142720b413b0"
},
"downloads": -1,
"filename": "play_dv_on_windows-1.0.13-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e4d4965ce0e9444e2a3e72343f2069f5",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 32131,
"upload_time": "2025-07-11T08:12:10",
"upload_time_iso_8601": "2025-07-11T08:12:10.021591Z",
"url": "https://files.pythonhosted.org/packages/99/e9/344d9dce8180f6409b613c3c96d7bb7fac7f0c2c36b8ca10bae2bea87d59/play_dv_on_windows-1.0.13-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "262561fff1f7b239bef0c0ce0cee184872f4bc47702fde8e7ec9a77ce1bb174e",
"md5": "62de6be38d53ceee364fff3a77c24d80",
"sha256": "e446fd6884509ee0d191fd8ad5279b1c7e8e8595f509970fffb6f1f3578281d7"
},
"downloads": -1,
"filename": "play_dv_on_windows-1.0.13.tar.gz",
"has_sig": false,
"md5_digest": "62de6be38d53ceee364fff3a77c24d80",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 50175,
"upload_time": "2025-07-11T08:12:11",
"upload_time_iso_8601": "2025-07-11T08:12:11.201704Z",
"url": "https://files.pythonhosted.org/packages/26/25/61fff1f7b239bef0c0ce0cee184872f4bc47702fde8e7ec9a77ce1bb174e/play_dv_on_windows-1.0.13.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-11 08:12:11",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "anfen93",
"github_project": "play-dv-on-windows",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "requests",
"specs": [
[
">=",
"2.31.0"
]
]
},
{
"name": "psutil",
"specs": [
[
">=",
"5.9.0"
]
]
}
],
"lcname": "play-dv-on-windows"
}
JSON
