media-muncher

A Python library for working with media assets, in particular DASH and HLS streams.

Features

• Content handlers — Fetch and parse HLS, DASH, VAST, VMAP, and static media (JPEG, PNG, MP4)
• Stream analysis — Extract renditions, packaging info, and timeline data from HLS/DASH manifests
• Metadata extraction — Summarise manifests as features, structure, facets, or plain-text digests
• HLS download — Offline download of HLS streams with parallel segment fetching
• Encoding utilities — Frame rates, resolutions, H.264 level validation, GOP sizing, segment duration math
• HLS compatibility — Compare renditions between two HLS sources by codec strings
• Transcoding profiles — Pluggable schema system to build transcoding profiles from analysed streams (currently ships with Broadpeak.io bkt-v1, bkt-v2, and bkt-v2.1 schemas)

Requirements

• Python 3.10 or higher (up to 3.13)
• MediaInfo installed on the system (required by pymediainfo for segment probing when manifest metadata is incomplete)

Installation

From PyPI

pip install media-muncher

Monorepo development

From the repository root, use the unified dev environment (build order: mpd-inspector → media-muncher → SDK → CLI):

python3 build-scripts/setup-unified-env.py

Quick example

Fetch and inspect a stream:

from media_muncher.handlers import factory

handler = factory.create_handler("https://example.com/main.m3u8")
print(handler.document)
print(handler.extract_features())

Analyse renditions and optionally generate a transcoding profile:

from media_muncher.handlers.hls import HLSHandler
from media_muncher.analysers.hls import HlsAnalyser
from media_muncher.profile import ABRProfileGenerator

handler = HLSHandler(url="https://example.com/main.m3u8")
analyser = HlsAnalyser(handler)
renditions = analyser.extract_renditions()
packaging = analyser.extract_packaging_info()

# Schema is pluggable; bkt-v2.1 is the current built-in schema
profile = ABRProfileGenerator(schema="bkt-v2.1", preset="VERYFAST").generate(
    renditions, packaging, name="MyProfile"
)

Documentation

Full documentation is available as an MkDocs site in this package:

cd media-muncher
poetry install
poetry run mkdocs serve

Then open http://127.0.0.1:8000.

See the docs/ directory for guides and API reference.

Development

Run tests from the media-muncher/ directory:

poetry install
poetry run pytest

Test layout:

• tests/dimensions/ — Unit tests for encoding math (FrameRate, Resolution, H.264 levels, GOP/segment sizing)
• tests/profile_generator/ — End-to-end profile generation against local manifest fixtures
• tests/test_file_handlers.py — Handler factory and content-type detection (requires network)
• tests/manifest_samples/ — HLS/DASH manifest fixtures used by profile tests

Build documentation:

poetry run mkdocs build