cymedia 0.1.0a1__tar.gz

cymedia-0.1.0a1/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## 0.1.0a1
+
+First alpha.
+
+- Graph engine: decode once, a filter chain and an encoder per branch, source group and object
+  numbers carried to every output, a keyframe at each group start.
+- Realtime drop policy at group granularity, with input and branch events; frames wait while a
+  branch's encoder first opens.
+- C sink ABI, a queue sink for Python, and native sinks passed as capsules.
+- ABR ladder profiles for NVENC and software, and a live delay bench.

cymedia-0.1.0a1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Giovanni Marzot
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cymedia-0.1.0a1/MANIFEST.in

@@ -0,0 +1,4 @@
+include LICENSE README.md CHANGELOG.md
+recursive-include src/cymedia *.pyx *.c *.h
+recursive-include tests *.py
+exclude src/cymedia/_core.c

cymedia-0.1.0a1/PKG-INFO

@@ -0,0 +1,139 @@
+Metadata-Version: 2.4
+Name: cymedia
+Version: 0.1.0a1
+Summary: Low-latency, group-aligned media processing graphs on FFmpeg's libraries
+Author: Giovanni Marzot
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/gmarzot/cymedia
+Project-URL: Repository, https://github.com/gmarzot/cymedia
+Project-URL: Issues, https://github.com/gmarzot/cymedia/issues
+Project-URL: Changelog, https://github.com/gmarzot/cymedia/blob/main/CHANGELOG.md
+Keywords: ffmpeg,video,transcoding,abr,nvenc,low-latency,moq
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: C
+Classifier: Programming Language :: Cython
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Video :: Conversion
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Dynamic: license-file
+
+# cymedia
+
+Low-latency, group-aligned media processing graphs on FFmpeg's libraries, for Python.
+
+A graph decodes a source once and feeds any number of branches. Each branch is a libavfilter
+chain ending in an encoder, and its output goes to a sink. Source group numbers, object numbers
+and timestamps pass through unchanged, and every branch starts a keyframe at each source group
+start, so equally numbered groups line up across all outputs. The first graph is an ABR ladder.
+
+**Status: alpha.** The NVIDIA path (NVDEC, `scale_cuda`, NVENC) and a software path (libopenh264,
+else libx264) work, on Linux and macOS with Python 3.12 and 3.13. The API can change before 1.0.
+
+## Install
+
+cymedia builds against the system's FFmpeg, 6.1 or later. It needs FFmpeg's development files,
+`pkg-config` and a C compiler:
+
+    sudo apt-get install pkg-config libavcodec-dev libavfilter-dev libavutil-dev   # Ubuntu 24.04
+    brew install ffmpeg pkg-config                                                 # macOS
+    pip install cymedia
+
+Prebuilt wheels with an LGPL FFmpeg are planned.
+
+## Example
+
+```python
+from cymedia import Rung, ladder
+
+rungs = [Rung(1280, 720, 3_750_000), Rung(640, 360, 900_000)]
+with ladder(rungs, profile="nvenc", fps=(60, 1)) as g:
+    g.push(frame, group, obj, pts_us, key)  # one H.264 access unit
+    for out in g.read(timeout=0.1):
+        ...  # out.branch, out.group, out.object, out.pts_us, out.key, out.group_start, out.data
+```
+
+- **Input** is one H.264 access unit per `push()`: Annex B, or 4-byte length prefixes with the
+  avcC passed as `extradata=`. `key` marks a group's first frame. `push()` returns False when
+  the frame was dropped.
+- **Output** is Annex B, one `Output` per encoded frame, carrying its source frame's group,
+  object and timestamp. `g.fileno()` is readable while outputs are queued, for an event loop:
+  `loop.add_reader(g.fileno(), lambda: handle(g.read(0)))`.
+- **`flush(timeout)`** ends input and waits for every branch's last frame; `stats()` and
+  `delays(branch)` report counters and recent push-to-output delays.
+
+### Profiles
+
+| Profile | Decode | Scale | Encode |
+|---|---|---|---|
+| `nvenc` | NVDEC | `scale_cuda` | `h264_nvenc`: p1, ultra low latency, CBR, no B-frames; filler NAL units stripped |
+| `cpu` | software | `scale` | libopenh264, else libx264 (veryfast, zerolatency) |
+
+Any other graph is a list of branches:
+
+```python
+from cymedia import Branch, Graph
+
+g = Graph([Branch("scale=640:360,format=yuv420p", "libx264", {"preset": "veryfast"})],
+          decoder="h264", fps=(30, 1))
+```
+
+## How it runs
+
+- One decode thread decodes each source frame once, then runs every branch's filter chain.
+- Each branch encodes on its own thread. Python's GIL is released throughout.
+- In realtime mode (the default) a full queue drops instead of blocking. Input resumes at the next
+  group start; a branch that falls behind abandons the rest of that group, so a group is cut
+  short and never has a hole in it. While a branch's encoder first opens, frames wait rather
+  than drop. With `realtime=False`, queues block instead.
+- Outputs go to a sink with a C ABI ([`cymedia_sink.h`](https://github.com/gmarzot/cymedia/blob/main/src/cymedia/cymedia_sink.h)). The
+  default sink queues them for `Graph.read()`; a native consumer passes its own sink as a
+  `cymedia.sink` capsule and keeps frames out of Python entirely.
+
+## Measured delay
+
+An RTX 4070, a 2160p60 H.264 source to six NVENC rungs (1440p to 180p), from `push()` to the
+encoded output, the 4K decode included (about 4.4 ms of it):
+
+| Run | GPU power state | p50 | p99 |
+|---|---|---|---|
+| 60 fps | P2, then P3 | 8.5–9.3 ms | 14.6–15.3 ms |
+| 60 fps, clocks held up | P2 | 7.4–8.0 ms | 15.5–17.1 ms |
+| 30 fps | P5 | 14.7–16.1 ms | 29.7–30.7 ms |
+| 30 fps, clocks held up | P2/P3 | 8.5–9.0 ms | 16.0–16.9 ms |
+
+Under a light load a GeForce card drops to a low power state and the delay doubles; no frames are
+held. [`bench/ladder_delay.py`](https://github.com/gmarzot/cymedia/blob/main/bench/ladder_delay.py) measures it on your hardware.
+
+## Used by
+
+[aiomoqt](https://github.com/gmarzot/aiomoqt)'s `abr_ingest` sits in front of a MoQ relay and
+publishes a broadcast plus a cymedia ladder under one catalog.
+
+## Develop
+
+    python -m venv .venv && .venv/bin/pip install "Cython>=3.0.10" "setuptools>=77" pytest
+    .venv/bin/pip install --no-build-isolation -e .
+    .venv/bin/python -m pytest -q
+
+GPU tests skip unless CUDA, `h264_nvenc` and `scale_cuda` are available. The delay bench:
+
+    .venv/bin/python bench/ladder_delay.py clip.mkv --profile nvenc --seconds 90
+
+Contributor rules are in [AGENTS.md](https://github.com/gmarzot/cymedia/blob/main/AGENTS.md).
+
+## License
+
+MIT. cymedia links FFmpeg dynamically. A build for distribution must link an LGPL-only FFmpeg
+(no `--enable-gpl`, no `--enable-nonfree`; `scale_cuda` built with `--enable-cuda-llvm`) and
+publish that FFmpeg's source and configure line. Distribution packages often ship GPL builds,
+which are fine for development but not for redistributed wheels. `cymedia.ffmpeg_info()` reports
+the license of the FFmpeg in use.

cymedia-0.1.0a1/README.md

@@ -0,0 +1,111 @@
+# cymedia
+
+Low-latency, group-aligned media processing graphs on FFmpeg's libraries, for Python.
+
+A graph decodes a source once and feeds any number of branches. Each branch is a libavfilter
+chain ending in an encoder, and its output goes to a sink. Source group numbers, object numbers
+and timestamps pass through unchanged, and every branch starts a keyframe at each source group
+start, so equally numbered groups line up across all outputs. The first graph is an ABR ladder.
+
+**Status: alpha.** The NVIDIA path (NVDEC, `scale_cuda`, NVENC) and a software path (libopenh264,
+else libx264) work, on Linux and macOS with Python 3.12 and 3.13. The API can change before 1.0.
+
+## Install
+
+cymedia builds against the system's FFmpeg, 6.1 or later. It needs FFmpeg's development files,
+`pkg-config` and a C compiler:
+
+    sudo apt-get install pkg-config libavcodec-dev libavfilter-dev libavutil-dev   # Ubuntu 24.04
+    brew install ffmpeg pkg-config                                                 # macOS
+    pip install cymedia
+
+Prebuilt wheels with an LGPL FFmpeg are planned.
+
+## Example
+
+```python
+from cymedia import Rung, ladder
+
+rungs = [Rung(1280, 720, 3_750_000), Rung(640, 360, 900_000)]
+with ladder(rungs, profile="nvenc", fps=(60, 1)) as g:
+    g.push(frame, group, obj, pts_us, key)  # one H.264 access unit
+    for out in g.read(timeout=0.1):
+        ...  # out.branch, out.group, out.object, out.pts_us, out.key, out.group_start, out.data
+```
+
+- **Input** is one H.264 access unit per `push()`: Annex B, or 4-byte length prefixes with the
+  avcC passed as `extradata=`. `key` marks a group's first frame. `push()` returns False when
+  the frame was dropped.
+- **Output** is Annex B, one `Output` per encoded frame, carrying its source frame's group,
+  object and timestamp. `g.fileno()` is readable while outputs are queued, for an event loop:
+  `loop.add_reader(g.fileno(), lambda: handle(g.read(0)))`.
+- **`flush(timeout)`** ends input and waits for every branch's last frame; `stats()` and
+  `delays(branch)` report counters and recent push-to-output delays.
+
+### Profiles
+
+| Profile | Decode | Scale | Encode |
+|---|---|---|---|
+| `nvenc` | NVDEC | `scale_cuda` | `h264_nvenc`: p1, ultra low latency, CBR, no B-frames; filler NAL units stripped |
+| `cpu` | software | `scale` | libopenh264, else libx264 (veryfast, zerolatency) |
+
+Any other graph is a list of branches:
+
+```python
+from cymedia import Branch, Graph
+
+g = Graph([Branch("scale=640:360,format=yuv420p", "libx264", {"preset": "veryfast"})],
+          decoder="h264", fps=(30, 1))
+```
+
+## How it runs
+
+- One decode thread decodes each source frame once, then runs every branch's filter chain.
+- Each branch encodes on its own thread. Python's GIL is released throughout.
+- In realtime mode (the default) a full queue drops instead of blocking. Input resumes at the next
+  group start; a branch that falls behind abandons the rest of that group, so a group is cut
+  short and never has a hole in it. While a branch's encoder first opens, frames wait rather
+  than drop. With `realtime=False`, queues block instead.
+- Outputs go to a sink with a C ABI ([`cymedia_sink.h`](https://github.com/gmarzot/cymedia/blob/main/src/cymedia/cymedia_sink.h)). The
+  default sink queues them for `Graph.read()`; a native consumer passes its own sink as a
+  `cymedia.sink` capsule and keeps frames out of Python entirely.
+
+## Measured delay
+
+An RTX 4070, a 2160p60 H.264 source to six NVENC rungs (1440p to 180p), from `push()` to the
+encoded output, the 4K decode included (about 4.4 ms of it):
+
+| Run | GPU power state | p50 | p99 |
+|---|---|---|---|
+| 60 fps | P2, then P3 | 8.5–9.3 ms | 14.6–15.3 ms |
+| 60 fps, clocks held up | P2 | 7.4–8.0 ms | 15.5–17.1 ms |
+| 30 fps | P5 | 14.7–16.1 ms | 29.7–30.7 ms |
+| 30 fps, clocks held up | P2/P3 | 8.5–9.0 ms | 16.0–16.9 ms |
+
+Under a light load a GeForce card drops to a low power state and the delay doubles; no frames are
+held. [`bench/ladder_delay.py`](https://github.com/gmarzot/cymedia/blob/main/bench/ladder_delay.py) measures it on your hardware.
+
+## Used by
+
+[aiomoqt](https://github.com/gmarzot/aiomoqt)'s `abr_ingest` sits in front of a MoQ relay and
+publishes a broadcast plus a cymedia ladder under one catalog.
+
+## Develop
+
+    python -m venv .venv && .venv/bin/pip install "Cython>=3.0.10" "setuptools>=77" pytest
+    .venv/bin/pip install --no-build-isolation -e .
+    .venv/bin/python -m pytest -q
+
+GPU tests skip unless CUDA, `h264_nvenc` and `scale_cuda` are available. The delay bench:
+
+    .venv/bin/python bench/ladder_delay.py clip.mkv --profile nvenc --seconds 90
+
+Contributor rules are in [AGENTS.md](https://github.com/gmarzot/cymedia/blob/main/AGENTS.md).
+
+## License
+
+MIT. cymedia links FFmpeg dynamically. A build for distribution must link an LGPL-only FFmpeg
+(no `--enable-gpl`, no `--enable-nonfree`; `scale_cuda` built with `--enable-cuda-llvm`) and
+publish that FFmpeg's source and configure line. Distribution packages often ship GPL builds,
+which are fine for development but not for redistributed wheels. `cymedia.ffmpeg_info()` reports
+the license of the FFmpeg in use.

cymedia-0.1.0a1/pyproject.toml

@@ -0,0 +1,51 @@
+[build-system]
+requires = ["setuptools>=77", "Cython>=3.0.10"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "cymedia"
+version = "0.1.0a1"
+description = "Low-latency, group-aligned media processing graphs on FFmpeg's libraries"
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Giovanni Marzot" }]
+keywords = ["ffmpeg", "video", "transcoding", "abr", "nvenc", "low-latency", "moq"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: MacOS",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: C",
+    "Programming Language :: Cython",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Multimedia :: Video :: Conversion",
+]
+
+[project.urls]
+Homepage = "https://github.com/gmarzot/cymedia"
+Repository = "https://github.com/gmarzot/cymedia"
+Issues = "https://github.com/gmarzot/cymedia/issues"
+Changelog = "https://github.com/gmarzot/cymedia/blob/main/CHANGELOG.md"
+
+[project.optional-dependencies]
+test = ["pytest>=8"]
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+packages = ["cymedia"]
+
+[tool.setuptools.package-data]
+cymedia = ["*.h"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "W"]

cymedia-0.1.0a1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

cymedia-0.1.0a1/setup.py

@@ -0,0 +1,21 @@
+import subprocess
+
+from Cython.Build import cythonize
+from setuptools import Extension, setup
+
+LIBS = ["libavcodec", "libavfilter", "libavutil"]
+
+
+def pkg_config(flag):
+    return subprocess.check_output(["pkg-config", flag, *LIBS], text=True).split()
+
+
+ext = Extension(
+    "cymedia._core",
+    sources=["src/cymedia/_core.pyx", "src/cymedia/engine.c", "src/cymedia/qsink.c"],
+    include_dirs=["src/cymedia"],
+    extra_compile_args=pkg_config("--cflags") + ["-std=c11", "-O2", "-Wall"],
+    extra_link_args=pkg_config("--libs") + ["-lpthread"],
+)
+
+setup(ext_modules=cythonize([ext], compiler_directives={"language_level": 3}))

cymedia-0.1.0a1/src/cymedia/__init__.py

@@ -0,0 +1,8 @@
+"""Low-latency, group-aligned media processing graphs on FFmpeg's libraries."""
+from cymedia._core import (Graph, ffmpeg_info, have_decoder, have_encoder, have_filter,
+                           hw_available, set_ffmpeg_log_level)
+from cymedia._types import Branch, Output
+from cymedia.ladder import PROFILES, Rung, ladder
+
+__all__ = ["Branch", "Graph", "Output", "PROFILES", "Rung", "ffmpeg_info", "have_decoder",
+           "have_encoder", "have_filter", "hw_available", "ladder", "set_ffmpeg_log_level"]