Lib.rs

› Parser implementations
#webm #matroska #mkv #ebml #command-line-tool #cli

bin+lib mkvdump

MKV and WebM parser CLI tool

by Carlos Bentzen

14 releases (4 breaking)

0.6.0 May 24, 2023
0.5.2 May 16, 2023
0.4.5 May 14, 2023
0.3.1 Sep 15, 2022
0.2.1 Aug 17, 2022

#666 in Parser implementations

39 downloads per month

MIT/Apache

71KB
1.5K SLoC

mkvdump

coverage test Crates.io

A command-line tool for debugging Matroska/WebM files. It displays all internal elements of a Matroska file as JSON or YAML.

Sample YAML output 
- id: EBML
  header_size: 5
  size: 36
  children:
  - id: EBMLVersion
    header_size: 3
    size: 4
    value: 1
  - id: EBMLReadVersion
    header_size: 3
    size: 4
    value: 1
  - id: EBMLMaxIDLength
    header_size: 3
    size: 4
    value: 4
  - id: EBMLMaxSizeLength
    header_size: 3
    size: 4
    value: 8
  - id: DocType
    header_size: 3
    size: 7
    value: webm
  - id: DocTypeVersion
    header_size: 3
    size: 4
    value: 2
  - id: DocTypeReadVersion
    header_size: 3
    size: 4
    value: 2
- id: Segment
  header_size: 12
  size: Unknown
  children:
  - id: Void
    header_size: 9
    size: 229
    value: null
  - id: Info
    header_size: 5
    size: 44
    children:
    - id: TimestampScale
      header_size: 4
      size: 7
      value: 1000000
    - id: MuxingApp
      header_size: 3
      size: 16
      value: Lavf58.29.100
    - id: WritingApp
      header_size: 3
      size: 16
      value: Lavf58.29.100
  - id: Tracks
    header_size: 5
    size: 101
    children:
    - id: TrackEntry
      header_size: 9
      size: 96
      children:
      - id: TrackNumber
        header_size: 2
        size: 3
        value: 1
      - id: TrackUID
        header_size: 3
        size: 4
        value: 1
      - id: FlagLacing
        header_size: 2
        size: 3
        value: 0
      - id: Language
        header_size: 4
        size: 7
        value: und
      - id: CodecID
        header_size: 2
        size: 7
        value: V_AV1
      - id: TrackType
        header_size: 2
        size: 3
        value: video
      - id: DefaultDuration
        header_size: 4
        size: 8
        value: 41708333
      - id: Video
        header_size: 9
        size: 32
        children:
        - id: PixelWidth
          header_size: 2
          size: 4
          value: 1280
        - id: PixelHeight
          header_size: 2
          size: 4
          value: 720
        - id: Colour
          header_size: 3
          size: 15
          children:
          - id: Range
            header_size: 3
            size: 4
            value: broadcast range
          - id: ChromaSitingHorz
            header_size: 3
            size: 4
            value: left collocated
          - id: ChromaSitingVert
            header_size: 3
            size: 4
            value: half
      - id: CodecPrivate
        header_size: 3
        size: 20
        value: '[81 05 0c 00 0a 0b 00 00 00 2d 4c ff b3 df ff 98 04]'
  - id: Tags
    header_size: 5
    size: 61
    children:
    - id: Tag
      header_size: 10
      size: 56
      children:
      - id: Targets
        header_size: 10
        size: 10
        children: []
      - id: SimpleTag
        header_size: 10
        size: 36
        children:
        - id: TagName
          header_size: 3
          size: 10
          value: ENCODER
        - id: TagString
          header_size: 3
          size: 16
          value: Lavf58.29.100
  - id: Cluster
    header_size: 6
    size: 2679
    children:
    - id: Timestamp
      header_size: 2
      size: 3
      value: 0
    - id: SimpleBlock
      header_size: 2
      size: 45
      value:
        track_number: 1
        timestamp: 0
        keyframe: true
    - id: SimpleBlock
      header_size: 2
      size: 59
      value:
        track_number: 1
        timestamp: 42
    - id: SimpleBlock
      header_size: 2
      size: 32
      value:
        track_number: 1
        timestamp: 83
    # ...

What's it useful for?

This tool is similar to mp4dump, but for Matroska files. It may be useful for:

  • snapshot testing: you can save mkvdump's output for a produced Matroska asset and use that in a human-readable snapshot test.
  • learning about EBML/Matroska/WebM: with this tool you can see how a Matroska file is structured. I also learned by writing the tool 😊

Getting mkvdump

Debian package

Ubuntu users (>= 20.04) can install mkvdump via the DEB package available in the releases page.

Homebrew

Linux and macOS users on x86_64 devices can install mkvdump via the Homebrew tap:

$ brew install cadubentzen/mkvdump/mkvdump

macOS users on M1 or M2 devices need to use

$ brew install --build-from-source cadubentzen/mkvdump/mkvdump

Cargo

If you have cargo-binstall installed, you can install mkvdump with

$ cargo binstall mkvdump

Else, you can install by building it from source with:

$ cargo install mkvdump

Docker

To pull latest mkvdump from Docker Hub:

$ docker pull cadubentzen/mkvdump

A GitHub package is also available via

$ docker pull ghcr.io/cadubentzen/mkvdump

Images are multi-arch with support for linux/amd64, linux/386, linux/arm64, linux/arm/v7 and linux/arm/v6.

Running the container

Asssuming a Mastroska file in the host located at /host-path/sample.mkv. You can run mkvdump on it with the following command, by mounting a volume:

$ docker run -v /host-path:/media cadubentzen/mkvdump /media/sample.mkv

Prebuilt binaries

Download prebuilt binaries from the release page. There are binaries for the following targets:

  • Linux
    • statically linked with musl: x86_64, x86, aarch64, armv7l and armv6l
    • with GNU libc: x86_64 and x86 (built on Ubuntu 20.04)
  • macOS
    • x86_64 and aarch64 (>= macOS 11 Big Sur)
  • Windows
    • x86_64 and x86 with MSVC and MinGW

License

© 2022 Carlos Bentzen cadubentzen@gmail.com.

This project is licensed under either of

at your option.

The SPDX license identifier for this project is MIT OR Apache-2.0.

Dependencies

~7MB
~135K SLoC