KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #ai-agent #developer-tools #codex #typescript #cli #deepseek-harness #claude-code #ai-agents #mcp #rust

Extract-MKV

★ 4 Open GitHub ↗

Use MakeMKV and MKVToolNix to automate remuxing blurays

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Extract-MKV

A script to remux blurays into mkv files using MakeMKV in a repeatable way.
MakeMKV's interface is fine, but movies can have several tracks that need to be identified and tagged, and once you've closed the program that info is lost and all needs to be redone.
By defining in a json file what should be done with each movie, it can be rerun and tweaked to standardize the library or fix mistakes without configuring everything from scratch.

## How it works

MakeMKV's command line does not provide most of the options available in the interface, so two passes are needed.
1. MakeMKV extracts the chosen title with all available streams included
2. MKVToolNix's mkvmerge is used to remux the streams and set attributes

## Usage

`python ./extract-mkv.py SELECTION`

- **SELECTION**: A comma separated list of names, disc identifiers, or ALL to extract all discs
- **--force** (optional): If the output mkv file already exists, overwrite it instead of skipping the title
- **--verbose** (optional): Log out extra information, as well as MakeMKV and MKVToolNix output

## Configuration

Create an `env.json` file next to the main script containing the following properties
```json
{
    "makemkvcon": "C:\\path\\to\\makemkvcon64.exe",
    "mkvmerge": "C:\\path\\to\\mkvmerge.exe",
    "source": "path\\to\\bdmv\\folders",
    "destination": "path\\to\\put\\mkvs",
    "config": "path\\to\\media.json"
}
```

- **makemkvcon**: Optional path to the makemkvcon executable
- **mkvmerge**: Optional path to the mkvmerge executable
- **source**: Required path to the folder containing all of the BDMV/ISOs
- **destination**: Required path where mkv files should be created
- **config**: Required path to a config file containing movie definitions
- **temp**: Optional working directory instead of the standard temp location

The `media.json` file stores definitions for how to handle each movie
```json
{
    "DISCID": {
        "TITLEID": {
            "name": "Movie Name",
            "year": 2021,
            "audio": [
                {
                    "track": 0,
                    "name": "5.1 DTS-HD Master Audio",
                    "default": true
                }
            ],
            "subtitle": [
                {
                    "track": 0,
                    "name": "English"
                },
                {
                    "track": { "index": 0, "forced": true },
                    "name": "English (forced)",
                    "forced": true
                }
            ]
        }
    }
}
```
- **DISCID**: The name of the folder containing the BDMV/CERTIFICATE/etc folder structure
- **TITLEID**: The 'source file name' in the MakeMKV interface for the desired title
- **name**: The name of the movie/series
- **year**: The release year of the movie/series
- **version**: The specific version of the movie
- **3d**: The 3D format of the movie (ex `MVC` or `SBS`)
- **season**: The season of the episode
- **episode**: The episode number within the season
- **title**: The title of the specific episode
- **order**: The display order for the show (ex `aired` or `dvd`)
- **extra**: The name of the extra (setting this value marks this title as an extra)
- **type**: The extras folder name to use (only used if `extra` is set) (defaults to `extras`)
- **path**: Where to put the movie relative to `env.json:destination`
- Track options (track order is determined by definition order)
  - **track**: Track identification (a number is equivalent to only specifying `index`)
    - **source**: Specify a DISCID to pull this track from a different source
    - **title**: Specify a TITLEID to pull this track from (required if `source` is specified)
    - **index**: The index of the track in the MakeMKV interface (first audio track is 0) (core/forced tracks are not counted)
    - **core**: Select an audio track's core
    - **forced**: Select the forced subtitles track
  - **name**: The display name of the track
  - **language**: The language code for the track
  - **default**: Set true if the track should have the default flag
  - **forced**: Set true if the track should have the forced flag
  - **commentary**: Set true if the track should have the commentary flag
  - **sync**: Set the milliseconds to offset the track, or `{ offset, factor, divisor }` matching mkvmerge's `--sync [track]:[offset],[factor]/[divisor]`
  - **cropping**: Set `{ left, top, right, bottom }` to inform players to crop pixels without reencoding (few players actually support this)

## Extra notes

- Some movies include a comment like `FPL_MainFeature` on certain titles, this can be used as a `TITLEID`
- For DVD ISOs, set `DISCID="file.iso"` and `TITLEID="01"` using the 'Source title ID' shown in MakeMKV
- Uniquely identify BDMVs with a sha1 hash: `DISCID="[DISC_NAME]:[SHA1]"`
  - If a SHA1 hash is specified then DISC_NAME will not be used for identification and is only for display
  - Hashes are only used for BDMV folders, ISOs are not hashed and will not be found if a hash is specified
  - Hashes can be of `MAKEMKV/AACS/Unit_Key_RO.inf` or a manifest of all files in the BDMV folder
  - The `./identify-path.py` script will compute the hashes that can be used for a folder
- Set the env.json config property to an array to split definitions across multiple files
- The env.json config property can use glob format instead of listing every file
- Files are generated at `[destination]/[path]/[name] ([year])/[name] ([year]).mkv`
  - If it is a movie extra then `[destination]/[path]/[name] ([year])/[type]/[extra].mkv`
  - If season and episode then `[destination]/[path]/[name] ([year])/Season [season]/[name] S[season]E[episode].mkv`
  - If a season extra then `[destination]/[path]/[name] ([year])/Season [season]/[type]/[extra].mkv`
  - If version is specified it is added at the end of the path with `[...] - [version].mkv`
  - If it is marked as 3D the format is added to the extension as `[...].3D.[3d].mkv`
- Setting the episode order for a show creates a tvshow.nfo file (if the file already exists you will have to manually update it)
- Values in `DISCID=""` act as defaults for all titles in the file, handy to avoid repeatedly specifying the path or series name
- Values in `TITLEID=""` act as defaults for all titles in the disc, handy to avoid repeatedly specifying the movie name and year
- Some movies have several titles with the same source file, differentiated using an angle number `TITLEID="00245.mpls(1)"`
- Use a relative path `TITLEID` starting with `./` to reference mkvmerge compatible files `DISCID="english.srt"` `TITLEID="./"`
  - This can also be used when MakeMKV does not find a title in a BDMV `TITLEID="./BDMV/STREAM/50356.m2ts"`
- MakeMKV will not export 3D video by default, update the advanced selection rules from `-sel:mvcvideo` to `+sel:mvcvideo`
- If video tracks are not specified, the first video track is used with all default values
- If audio tracks are not specified, the first audio track is used with all default values
- If subtitle tracks are not specified, the output will not have any subtitles included
- Use the MakeMKV flatpak by setting env.json makemkvcon to `["flatpak", "run", "--command=makemkvcon", "com.makemkv.MakeMKV"]`
- Use the MKVToolnix flatpak by setting env.json mkvmerge to `["flatpak", "run", "--command=mkvmerge", "org.bunkus.mkvtoolnix-gui"]`

## Helper Scripts

`python ./identify-path.py PATH_OR_NAME`

Given the name of a BDMV folder or a path to it, locate it and print out the identifier hashes that could be used as a `DISCID` for it.

`python ./identify-conflicts.py`

Scan and identify everything in the source directory, and log a warning for any discs that have the same identifier hash. Identifier hashes should never match for images of different discs.

## TODO

- Support for DVDs in a VIDEO_TS folder structure
- Set chapter names
- Concatenate multiple titles into a single file, to support two disc movies
- Split titles on chapters or at specific times, to split episodes or remove credits
- Support for Jellyfin's multipart naming convention (... part1.mkv)

Extract-MKV

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README