Metadata-Version: 2.4
Name: media-muncher
Version: 2.2.0
Summary: A module to work with media assets, in particular DASH and HLS streams
License: MIT
License-File: LICENSE.md
Author: Fabre Lambeau
Author-email: fabre.lambeau@broadpeak.tv
Requires-Python: >=3.10,<3.14
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Dist: isodate (>=0.6.1,<0.7.0)
Requires-Dist: loguru (>=0.7.2,<0.8.0)
Requires-Dist: lxml (>=5.2.2,<6.0.0)
Requires-Dist: m3u8 (>=4.1.0,<5.0.0)
Requires-Dist: mpd-inspector (>=1.2.3)
Requires-Dist: pymediainfo (>=7.0.0,<8.0.0)
Requires-Dist: requests (>=2.32.5,<3.0.0)
Description-Content-Type: text/markdown

# 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](https://mediaarea.net/en/MediaInfo) installed on the system (required by `pymediainfo` for segment probing when manifest metadata is incomplete)

## Installation

### From PyPI

```bash
pip install media-muncher
```

### Monorepo development

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

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

## Quick example

Fetch and inspect a stream:

```python
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:

```python
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:

```bash
cd media-muncher
poetry install
poetry run mkdocs serve
```

Then open [http://127.0.0.1:8000](http://127.0.0.1:8000).

See the [docs/](docs/) directory for guides and API reference.


## Development

Run tests from the `media-muncher/` directory:

```bash
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:

```bash
poetry run mkdocs build
```

