aio-ffmpeg 0.1.0__tar.gz

aio_ffmpeg-0.1.0/.gitea/workflows/ci.yml

@@ -0,0 +1,55 @@
+name: CI Pipeline
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main, develop]
+
+jobs:
+  lint-and-test:
+    name: Lint, Type Check and Tests
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python 3.14
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.14"
+
+      - name: Install FFmpeg
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y ffmpeg
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+
+      - name: Install dependencies
+        run: |
+          uv sync --extra dev
+
+      - name: Check code formatting (Ruff)
+        run: |
+          uv run ruff format --check src/ tests/ docs/
+
+      - name: Lint codebase (Ruff)
+        run: |
+          uv run ruff check src/ tests/ docs/
+
+      - name: Type check (Mypy)
+        run: |
+          uv run mypy src/
+
+      - name: Run unit & integration tests with coverage
+        run: |
+          uv run coverage run -m pytest tests/ -v
+          uv run coverage report -m
+
+      - name: Build distribution packages (Wheel & Sdist)
+        run: |
+          uv build

aio_ffmpeg-0.1.0/.gitea/workflows/release.yml

@@ -0,0 +1,52 @@
+name: Release Pipeline
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build-and-release:
+    name: Build and Verify Release Artifacts
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python 3.14
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.14"
+
+      - name: Install FFmpeg
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y ffmpeg
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+
+      - name: Install dependencies
+        run: |
+          uv sync --extra dev
+
+      - name: Lint and Typecheck
+        run: |
+          uv run ruff check src/ tests/ examples/
+          uv run mypy src/
+
+      - name: Run test suite
+        run: |
+          uv run pytest tests/ -v
+
+      - name: Build distribution packages (Wheel & Sdist)
+        run: |
+          uv build
+
+      - name: Upload distribution packages as artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist-packages
+          path: dist/*

aio_ffmpeg-0.1.0/.gitignore

@@ -0,0 +1,74 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual environments
+.venv/
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Testing & Linting
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
+
+# Graphify output directory
+graphify-out/
+
+# Media temporary files and test artifacts
+*.mp4
+*.mkv
+*.avi
+*.mp3
+*.aac
+*.wav
+*.flac
+*.m4a
+*.webm
+*.ogg
+*.ts
+*.srt
+*.vtt
+*.log
+*.txt
+!requirements*.txt
+!docs/**/*.txt
+output_examples/
+
+# IDE / Editor
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS generated
+.DS_Store
+Thumbs.db

aio_ffmpeg-0.1.0/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+Все заметные изменения в проекте `async-ffmpeg` документируются в этом файле.
+
+Формат основан на [Keep a Changelog](https://keepachangelog.com/ru/1.0.0/),
+и проект придерживается [Семантического версионирования](https://semver.org/lang/ru/).
+
+---
+
+## [0.1.0] - 2026-09-19
+
+### Добавлено
+- **Высокоуровневый клиент (`FFmpegClient`)**: единый фасад с методами `transcode`, `extract_audio`, `trim`, `concat`, `screenshot`, `thumbnails`, `convert`, `normalize_audio`, `scale`, `two_pass_transcode`, `create_contact_sheet`, `detect_silence` и `probe`.
+- **Конструктор команд (`FFmpegCommand`)**: строго упорядоченный fluent-builder аргументов FFmpeg CLI (глобальные опции -> входные параметры -> фильтры -> выходные параметры) с автоматической валидацией конфликтующих флагов.
+- **Декларативный конвейер медиа (`MediaPipeline`)**: пошаговое построение цепочек обработки (trim, scale, watermark, audio normalization) с компиляцией в единый процесс FFmpeg и валидацией на этапе сборки.
+- **Клиент инспекции (`FFprobe`) и строгие модели данных**: асинхронный запуск `ffprobe` с разбором JSON-вывода в типизированные frozen dataclass-модели (`MediaInfo`, `VideoStream`, `AudioStream`, `SubtitleStream`, `Chapter`, `StreamDisposition`).
+- **Модуль аппаратного ускорения (`HardwareAccel`)**: автоматическое обнаружение доступных GPU-ускорителей (CUDA/NVENC, AMD AMF, Intel QSV, D3D11VA, Apple VideoToolbox) и подбор оптимальных кодеков.
+- **Диспетчер процессов (`ProcessRunner`)**: асинхронное управление жизненным циклом подпроцессов через `asyncio.create_subprocess_exec()`, ограничение параллельности через `asyncio.Semaphore`, поддержка таймаутов и graceful shutdown (`q\n` -> SIGINT -> SIGKILL).
+- **Машиночитаемый парсер прогресса (`ProgressParser`)**: разбор протокола `-progress pipe:1` в реальном времени с вычислением процента выполнения, времени, FPS, битрейта и скорости кодирования.
+- **Объектно-ориентированный граф фильтров (`Filter`, `FilterChain`, `FilterGraph`, `ComplexFilterGraph`)**: фабричные функции для видео- и аудиофильтров (`scale`, `fps`, `crop`, `pad`, `rotate`, `overlay`, `drawtext`, `loudnorm`, `volume`, `amix`, `concat` и др.).
+- **Модуль интеграции с `async-yt-dlp` (`async_ffmpeg.integration`)**: функции `process_download_result`, `transcode_download`, `extract_download_audio` и класс `DownloadPostProcessor` на базе слабосвязанного протокола `DownloadResultProtocol`.
+- **Комплекс интерактивных примеров (`examples/`)**: 7 готовых сценариев (`simple_transcode`, `extract_audio`, `video_thumbnails`, `watermark_and_filters`, `stream_concat`, `hardware_acceleration`, `ytdlp_pipeline`).
+- **Инфраструктура и качество**: 118 автоматических тестов с 100% прохождением, поддержка Python 3.14+, строгая статическая типизация `mypy --strict` без единого `Any`, zero runtime dependencies (только стандартная библиотека Python).

aio_ffmpeg-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,77 @@
+# Руководство по внесению вклада (Contributing)
+
+Приветствуются любые улучшения, исправления ошибок и предложения новых функциональных возможностей в `async-ffmpeg`.
+
+---
+
+## 1. Стратегия ветвления (Branching Strategy)
+
+В репозитории используется модель Git Flow с двумя долгоживущими ветками:
+
+- **`main`**: стабильная (production) ветка. Содержит исключительно готовые к релизу версии кода. Прямые коммиты запрещены. Слияния осуществляются только из `develop` перед выпуском новой версии с созданием аннотированного тега (`vX.Y.Z`).
+- **`develop`**: ветка активной разработки. В неё интегрируются новые возможности и исправления через Pull Requests.
+- **Вспомогательные ветки**:
+  - `feature/<название>`: разработка новой функциональности (создаются от `develop`, сливаются в `develop`).
+  - `fix/<описание>` или `bugfix/<описание>`: устранение ошибок (создаются от `develop`, сливаются в `develop`).
+  - `hotfix/<описание>`: неотложные исправления для продакшна (создаются от `main`, сливаются в `main` и `develop`).
+
+---
+
+## 2. Процесс разработки
+
+1. Склонировать репозиторий:
+   ```bash
+   git clone ssh://git@localhost:2222/6aton/AsyncFFmpeg.git
+   cd AsyncFFmpeg
+   ```
+2. Создать рабочую ветку от актуального состояния `develop`:
+   ```bash
+   git checkout develop
+   git pull origin develop
+   git checkout -b feature/my-feature
+   ```
+3. Установить зависимости для разработки через менеджер `uv`:
+   ```bash
+   uv sync --extra dev
+   ```
+4. Внести изменения, соблюдая архитектурные принципы проекта.
+5. Написать модульные или интеграционные тесты в каталоге `tests/`.
+6. Убедиться в успешном прохождении всех локальных проверок качества.
+7. Зафиксировать изменения с понятными сообщениями коммитов и отправить ветку в удалённый репозиторий.
+
+---
+
+## 3. Стандарты качества кода
+
+Перед отправкой изменений обязательно выполнение всех автоматических проверок:
+
+```bash
+# Проверка форматирования и линтинга
+uv run ruff check src/ tests/ examples/ docs/
+uv run ruff format --check src/ tests/ examples/ docs/
+
+# Проверка строгой статической типизации (Zero Any policy)
+uv run mypy src/
+
+# Запуск полного набора тестов с анализом покрытия
+uv run pytest tests/ -v
+```
+
+---
+
+## 4. Архитектурные правила и ограничения
+
+1. **Zero Runtime Dependencies**:
+   - В секции `dependencies` файла `pyproject.toml` не допускаются внешние пакеты.
+   - Разрешено использование исключительно стандартной библиотеки Python 3.14+.
+   - Внешние интеграции (например, `async-yt-dlp`) оформляются как опциональные зависимости (`optional-dependencies`).
+2. **Строгая статическая типизация**:
+   - Политика `Zero Any`: использование типа `Any` строго запрещено во всех публичных и внутренних сигнатурах.
+   - Для всех моделей данных используются frozen dataclass со `slots=True` (`@dataclass(frozen=True, slots=True)`).
+   - Обязательно указание типов всех аргументов и возвращаемых значений (`-> None` для процедур).
+3. **Языковая политика**:
+   - Все docstrings, комментарии к коду и документация составляются на русском языке в нейтральной форме (инфинитивы, безличные конструкции, 3-е лицо; без использования местоимений первого и второго лица).
+   - Все идентификаторы (имена модулей, классов, методов, функций, переменных) именуются на английском языке по стандарту PEP 8.
+4. **Кроссплатформенность**:
+   - Пути к файлам нормализуются через `normalize_path_for_ffmpeg()` из `_compat.py`.
+   - Запуск подпроцессов учитывает специфику платформ (флаг `CREATE_NO_WINDOW` для Windows, сигналы завершения для POSIX).

aio_ffmpeg-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 async-ffmpeg contributors
+
+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.

aio_ffmpeg-0.1.0/PKG-INFO

@@ -0,0 +1,280 @@
+Metadata-Version: 2.5
+Name: aio-ffmpeg
+Version: 0.1.0
+Summary: Production-ready, strictly typed async wrapper for FFmpeg and FFprobe
+Project-URL: Homepage, https://github.com/baton-spb/AsyncFFmpeg
+Project-URL: Documentation, https://github.com/baton-spb/AsyncFFmpeg#readme
+Project-URL: Repository, https://github.com/baton-spb/AsyncFFmpeg.git
+Project-URL: Issues, https://github.com/baton-spb/AsyncFFmpeg/issues
+Author: async-ffmpeg contributors
+License-Expression: MIT
+License-File: LICENSE
+Keywords: aio,async,asyncio,audio,ffmpeg,ffprobe,streaming,transcode,video
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Multimedia :: Sound/Audio
+Classifier: Topic :: Multimedia :: Video
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Provides-Extra: dev
+Requires-Dist: coverage>=7.6.0; extra == 'dev'
+Requires-Dist: mypy>=1.13.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.8.0; extra == 'dev'
+Provides-Extra: ytdlp
+Requires-Dist: async-yt-dlp>=0.1.0; extra == 'ytdlp'
+Description-Content-Type: text/markdown
+
+# async-ffmpeg
+
+[![CI](https://github.com/baton-spb/AsyncFFmpeg/actions/workflows/ci.yml/badge.svg)](https://github.com/baton-spb/AsyncFFmpeg/actions)
+[![PyPI version](https://img.shields.io/pypi/v/async-ffmpeg.svg)](https://pypi.org/project/async-ffmpeg/)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
+[![Typing: Typed](https://img.shields.io/badge/typing-typed-green.svg)](https://peps.python.org/pep-0561/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+**async-ffmpeg** — современная, строго типизированная, production-ready асинхронная библиотека-обёртка над `ffmpeg` и `ffprobe` для Python 3.11+.
+
+Она построена непосредственно поверх `asyncio.create_subprocess_exec()` без сторонних C-библиотек, без устаревших binding-ов и с **нулевыми зависимостями времени выполнения** (zero runtime dependencies, только стандартная библиотека Python).
+
+---
+
+## Сравнение с аналогами
+
+| Возможность | `async-ffmpeg` | `ffmpeg-python` | `moviepy` | `subprocess` (ручной) |
+|:---|:---:|:---:|:---:|:---:|
+| **Нативная асинхронность (`asyncio`)** | **Да** | Нет | Нет | Требует ручной реализации |
+| **Зависимости времени выполнения** | **0 (только stdlib)** | 2 | 10+ (тяжёлые) | 0 |
+| **Строгая типизация (`mypy --strict`)** | **100% (Zero Any)** | Нет типов | Частичная | Нет |
+| **Парсинг прогресса в реальном времени** | **Да (`-progress pipe:1`)** | Нет | Tqdm (базовый) | Ручной парсинг |
+| **Безопасная остановка (Graceful Shutdown)** | **Да (`q\n` -> SIGINT)** | Нет | Нет | Нет |
+| **Многоуровневый API (Facade / Pipeline / Builder)** | **Да** | Только builder | Только facade | Нет |
+| **Автоопределение GPU (CUDA/AMF/QSV/Toolbox)** | **Да** | Нет | Нет | Нет |
+| **Поддержка современного Python 3.14+** | **Да** | Заброшен | Медленный | Да |
+
+---
+
+## Ключевые возможности
+
+- **Полноценная асинхронность**: неблокирующий запуск процессов через `asyncio.create_subprocess_exec()`, контроль конкурентности через `asyncio.Semaphore`.
+- **Строгая типизация**: 100% соответствие `mypy --strict` и `Zero Any policy`, frozen dataclass-модели со `slots=True`, маркер PEP 561 (`py.typed`).
+- **Машиночитаемый прогресс**: чтение и потоковый разбор протокола `-progress pipe:1` (кадры, время, битрейт, скорость кодирования, процент выполнения).
+- **Graceful Shutdown**: предотвращение повреждения медиафайлов (битых заголовков MP4 / unclosed `moov` atom) путём отправки `q` в stdin перед отправкой системных сигналов завершения.
+- **Трёхуровневый API**:
+  - **Facade (`FFmpegClient`)**: готовые методы для решения 95% повседневных задач.
+  - **Pipeline (`MediaPipeline`)**: декларативный конвейер цепочек обработки видео и аудио.
+  - **Command Builder (`FFmpegCommand`)**: строгий конструктор аргументов CLI с контролем порядка и валидацией конфликтов.
+- **Типизированный FFprobe**: детальный разбор контейнеров, видео/аудио/субтитр-потоков, глав и метаданных.
+- **Аппаратное ускорение**: автоопределение и конфигурация NVENC, AMF, QSV, D3D11VA, VideoToolbox.
+- **Интеграция с `async-yt-dlp`**: бесшовный конвейер загрузки и последующей обработки медиафайлов.
+
+---
+
+## Методы высокоуровневого клиента (`FFmpegClient`)
+
+| Метод | Назначение |
+|:---|:---|
+| `transcode(...)` | Универсальное перекодирование с контролем кодеков, битрейта, разрешения, FPS и фильтров. |
+| `extract_audio(...)` | Извлечение аудиодорожки (`-vn`) с конвертацией в AAC, MP3, FLAC, OPUS или WAV. |
+| `trim(...)` | Быстрая обрезка медиафрагментов по меткам времени (со stream copy или перекодированием). |
+| `concat(...)` | Склейка нескольких файлов без перекодирования (demuxer) или через граф фильтров. |
+| `screenshot(...)` | Извлечение одного кадра в указанной временной метке в высоком качестве. |
+| `thumbnails(...)` | Серийная генерация миниатюр по фиксированному интервалу, общему числу или частоте кадров. |
+| `convert(...)` | Быстрая смена контейнера (remuxing, например MKV -> MP4) со stream copy. |
+| `normalize_audio(...)` | Двухпроходная нормализация громкости по вещательному стандарту EBU R128 (`loudnorm`). |
+| `scale(...)` | Масштабирование видеоряда с сохранением исходной аудиодорожки без перекодирования. |
+| `two_pass_transcode(...)` | Двухпроходное кодирование с контролем битрейта и автоматической очисткой временных логов. |
+| `create_contact_sheet(...)` | Сборка раскадровки (storyboard/contact sheet) в виде сетки миниатюр (`tile`). |
+| `detect_silence(...)` | Детектирование тишины и пауз в аудиодорожке с получением интервалов (`SilenceInterval`). |
+| `probe(...)` | Детальный анализ метаданных файла или потока с возвратом типизированного `MediaInfo`. |
+
+---
+
+## Установка
+
+```bash
+# Базовая установка (zero external dependencies)
+uv add async-ffmpeg
+
+# Или через pip:
+pip install async-ffmpeg
+
+# С опциональной поддержкой интеграции с async-yt-dlp
+pip install "async-ffmpeg[ytdlp]"
+```
+
+Требования:
+- Python >= 3.14
+- Установленный в системе `ffmpeg` и `ffprobe` (в `PATH` или указанный через аргументы клиента / переменную `FFMPEG_PATH`)
+
+---
+
+## Быстрый старт
+
+### 1. Анализ медиафайла (`FFprobe`)
+
+```python
+import asyncio
+from async_ffmpeg import FFmpegClient
+
+
+async def main() -> None:
+    client = FFmpegClient()
+    info = await client.probe("video.mp4")
+
+    print(f"Формат: {info.format.format_long_name}")
+    print(f"Длительность: {info.duration} сек")
+
+    if info.primary_video:
+        v = info.primary_video
+        print(f"Видео: {v.codec_name}, {v.width}x{v.height} @ {v.frame_rate:.2f} fps")
+
+    if info.primary_audio:
+        a = info.primary_audio
+        print(f"Аудио: {a.codec_name}, {a.sample_rate} Hz, каналов: {a.channels}")
+
+
+asyncio.run(main())
+```
+
+### 2. Транскодирование с отслеживанием прогресса
+
+```python
+import asyncio
+from async_ffmpeg import FFmpegClient, ProgressInfo
+
+
+async def main() -> None:
+    client = FFmpegClient()
+
+    async def on_progress(p: ProgressInfo) -> None:
+        print(f"Прогресс: {p.percent:.1f}% | Скорость: {p.speed} | FPS: {p.fps:.1f}")
+
+    result = await client.transcode(
+        input="input.mp4",
+        output="output_720p.mp4",
+        video_codec="libx264",
+        crf=23,
+        resolution=(1280, 720),
+        audio_codec="aac",
+        audio_bitrate="128k",
+        on_progress=on_progress,
+    )
+    print(f"Готово за {result.duration_seconds:.2f} сек!")
+
+
+asyncio.run(main())
+```
+
+### 3. Декларативный конвейер (`MediaPipeline`)
+
+```python
+import asyncio
+from async_ffmpeg import FFmpegClient
+
+
+async def main() -> None:
+    client = FFmpegClient()
+
+    # Цепочка: обрезка -> масштабирование -> нормализация звука -> вывод
+    await (
+        client.pipeline("input.mp4")
+        .trim(start=10, duration=60)
+        .scale(1280, 720)
+        .normalize_audio(target_lufs=-16.0)
+        .output("highlight_720p.mp4")
+        .run()
+    )
+
+
+asyncio.run(main())
+```
+
+### 4. Интеграция с загрузчиком (`async-yt-dlp`)
+
+```python
+import asyncio
+from async_ffmpeg import FFmpegClient
+from async_ffmpeg.integration import process_download_result
+
+
+async def main() -> None:
+    # Загрузка через yt-dlp (или совместимый объект с протоколом DownloadResultProtocol)
+    # Предположим, результат загрузки сохранён в download_result
+    client = FFmpegClient()
+
+    # Автоматическое извлечение аудиодорожки или конвертация
+    post_result = await process_download_result(
+        download_result,
+        action="extract_audio",
+        client=client,
+        audio_format="mp3",
+        audio_bitrate="320k",
+    )
+    print(f"Обработано: {post_result.output_path}")
+
+
+asyncio.run(main())
+```
+
+---
+
+## Примеры использования (`examples/`)
+
+В каталоге [`examples/`](examples/) содержатся готовые исполняемые сценарии:
+
+1. [`simple_transcode.py`](examples/simple_transcode.py) — Базовое перекодирование с отслеживанием прогресса в реальном времени.
+2. [`extract_audio.py`](examples/extract_audio.py) — Извлечение звуковых дорожек в форматах MP3, AAC, FLAC и нормализация звука.
+3. [`video_thumbnails.py`](examples/video_thumbnails.py) — Снятие скриншотов, серийная генерация миниатюр и раскадровка (contact sheet).
+4. [`watermark_and_filters.py`](examples/watermark_and_filters.py) — Наложение водяных знаков и комплексных графов фильтров через `MediaPipeline`.
+5. [`stream_concat.py`](examples/stream_concat.py) — Склейка медиафайлов через демультиплексор (demuxer) и фильтр объединения.
+6. [`hardware_acceleration.py`](examples/hardware_acceleration.py) — Автоматическое обнаружение GPU и кодирование с аппаратным ускорением.
+7. [`ytdlp_pipeline.py`](examples/ytdlp_pipeline.py) — Полный конвейер скачивания и последующей обработки с `async-yt-dlp`.
+
+---
+
+## Архитектура и документация
+
+Подробная проектная документация доступна в каталоге [`docs/`](docs/):
+
+- [`architecture.md`](docs/architecture.md) — Системная архитектура, слои абстракции, управление процессами.
+- [`api-design.md`](docs/api-design.md) — Детальное описание публичного API и сигнатур.
+- [`research.md`](docs/research.md) — Исследование поведения FFmpeg CLI, протокола `-progress` и кодов возврата.
+- [`pipeline.md`](docs/pipeline.md) — Руководство по работе с `MediaPipeline`.
+- [`hardware.md`](docs/hardware.md) — Конфигурация и использование аппаратного ускорения (GPU).
+- [`integration.md`](docs/integration.md) — Взаимодействие с внешними загрузчиками и `async-yt-dlp`.
+
+---
+
+## Разработка и тестирование
+
+```bash
+# Установка dev-окружения
+uv sync --extra dev
+
+# Проверка форматирования и линтинга
+uv run ruff check src/ tests/ examples/ docs/
+uv run ruff format --check src/ tests/ examples/ docs/
+
+# Проверка строгой статической типизации
+uv run mypy src/
+
+# Запуск тестов
+uv run pytest tests/ -v
+```
+
+---
+
+## Лицензия
+
+Распространяется под лицензией [MIT](LICENSE).