@grundyjs/canvas-take 0.4.1 → 0.5.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@grundyjs/canvas-take",
-  "version": "0.4.1",
-  "description": "Record HTML canvas video with audio and export GIFs with pluggable encoders, Worker support and explicit resource cleanup",
+  "version": "0.5.0",
+  "description": "Record canvas video with audio and export offline H.264/AAC MP4 or GIF with pluggable encoders, Worker support and explicit resource cleanup",
   "type": "module",
   "files": [
     "dist",
@@ -9,9 +9,36 @@
     "ru/README.md",
     "LICENSE",
     "CHANGELOG.md",
-    "docs/gif-encoder.md"
+    "docs/gif-encoder.md",
+    "docs/gif-benchmark.md",
+    "docs/video-recording.md",
+    "docs/offline-video-api.md",
+    "docs/offline-video-adapters.md",
+    "docs/offline-aac.md",
+    "docs/drafts"
   ],
   "exports": {
+    "./video/aac": {
+      "types": "./dist/video-aac.d.ts",
+      "import": "./dist/video-aac.js",
+      "default": "./dist/video-aac.js"
+    },
+    "./video/aac-worker": "./dist/video-aac-worker.js",
+    "./video/webcodecs": {
+      "types": "./dist/video-webcodecs.d.ts",
+      "import": "./dist/video-webcodecs.js",
+      "default": "./dist/video-webcodecs.js"
+    },
+    "./video/mp4": {
+      "types": "./dist/video-mp4.d.ts",
+      "import": "./dist/video-mp4.js",
+      "default": "./dist/video-mp4.js"
+    },
+    "./video": {
+      "types": "./dist/video.d.ts",
+      "import": "./dist/video.js",
+      "default": "./dist/video.js"
+    },
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
@@ -35,19 +62,24 @@
     "./gif/worker-runtime": "./dist/gif-worker-runtime.js"
   },
   "scripts": {
-    "build": "tsc -p tsconfig.json && node scripts/build-gif.mjs",
+    "build": "tsc -p tsconfig.json && node scripts/build-adapters.mjs",
     "test": "npm run build && node --test test/*.test.mjs",
     "prepack": "npm run build",
     "prepublishOnly": "npm test",
     "test:package": "node scripts/test-package.mjs",
+    "test:release-video": "node scripts/test-release-video.mjs",
     "test:next": "node scripts/test-next.mjs",
-    "test:browser": "npm run build && playwright test"
+    "test:browser": "npm run build && playwright test",
+    "benchmark:gif": "npm run build && node scripts/benchmark-gif.mjs"
   },
   "devDependencies": {
+    "@mediabunny/aac-encoder": "1.65.0",
     "@playwright/test": "1.64.1",
     "esbuild": "0.28.2",
+    "ffmpeg-static": "5.3.0",
     "gifenc": "1.0.3",
     "gifuct-js": "2.1.2",
+    "mediabunny": "1.65.0",
     "typescript": "6.0.3"
   },
   "license": "MIT",
@@ -64,7 +96,11 @@
     "gif",
     "audio",
     "web-worker",
-    "typescript"
+    "typescript",
+    "webcodecs",
+    "mp4",
+    "aac",
+    "offline-video"
   ],
   "sideEffects": false,
   "publishConfig": {

package/ru/README.md

@@ -5,9 +5,11 @@
 [Сайт](https://grundyjs.ru/canvas-take/) · [npm](https://www.npmjs.com/package/@grundyjs/canvas-take) · [Ошибки и предложения](https://github.com/urffin/canvas-take/issues)
 
 Независимая TypeScript-библиотека для записи видео с HTML canvas с необязательными
-аудиодорожками и покадрового экспорта GIF через отдельную точку входа. Без внешних
-зависимостей во время выполнения и без зависимости от AlgiViz. Только ESM,
-с декларациями TypeScript. Лицензия MIT. Пакет не запускает и не рисует вашу анимацию.
+аудиодорожками, офлайн-экспорта MP4 H.264/AAC и GIF через отдельные точки входа.
+Без внешних runtime npm-зависимостей и без зависимости от AlgiViz. Только ESM,
+с декларациями TypeScript. Код CanvasTake — MIT; опциональные адаптеры включают
+[Mediabunny MPL-2.0](../docs/offline-video-adapters.md#distribution-and-sources) и
+[AAC WASM / FFmpeg LGPL](../docs/offline-aac.md#distribution-and-source). Пакет не запускает и не рисует вашу анимацию.
 
 ## Установка
 
@@ -39,11 +41,11 @@ recorder.dispose();
 При записи со звуком варианты VP9 и VP8 включают Opus. Явно заданный неподдерживаемый
 MIME вызывает ошибку без скрытой смены формата. Результат содержит фактический MIME
 и соответствующее расширение. FPS и битрейт — целевые значения, а не гарантии.
-durationMs измеряет реальное время записи, а не длительность, прочитанную из файла.
+`durationMs` измеряет активное время записи без пауз, а не длительность, прочитанную из файла.
 
 Не меняйте размеры битовой карты canvas от start до stop. Масштабирование через CSS
 допускается. Изменение размеров завершает запись ошибкой. Canvas должен оставаться
-origin-clean. Захват экрана, пауза записи, покадровое кодирование видео и отправка
+origin-clean. Захват экрана, покадровое кодирование видео и отправка
 на сервер не поддерживаются. Фрагменты хранятся в памяти: ограничивайте длительность.
 Если замедление фоновой вкладки недопустимо, вызывайте dispose при скрытии страницы.
 Поддержка кодеков зависит от браузера и доступных ресурсов.
@@ -67,11 +69,65 @@ WebM от MediaRecorder может не содержать метаданные
 | `videoBitsPerSecond` | Необязательный положительный конечный целевой битрейт кодировщика |
 | `mimeType` | Необязательный явно заданный поддерживаемый MIME `video/webm` или `video/mp4`, включая кодеки |
 | `audioTracks` | Необязательный список только для чтения из активных звуковых `MediaStreamTrack`; без него или с пустым списком запись идёт без звука |
+| `maxDurationMs` | С 0.5.0: положительное безопасное целое, лимит активного времени в мс без пауз |
 
-`stop()` возвращает `{ blob, mimeType, extension, durationMs }`. Используйте рекордер
+`stop()` возвращает `{ blob, mimeType, extension, durationMs, stopReason }` (поле `stopReason` доступно с 0.5.0). Используйте рекордер
 в try/finally и вызывайте `dispose()`, даже если анимация завершилась ошибкой.
 Освобождайте object URL, когда они больше не нужны.
 
+## Пауза, продолжение и лимит времени (с версии 0.5.0)
+
+```js
+const recorder = createCanvasRecorder(canvas, { fps: 30, maxDurationMs: 30_000 });
+try {
+    await recorder.start();
+    // В обработчиках UI: await recorder.pause(); await recorder.resume();
+    const result = await recorder.finished;
+    console.log(result.stopReason, result.durationMs);
+} finally {
+    recorder.dispose();
+}
+```
+
+`pause()` и `resume()` завершаются после соответствующих событий MediaRecorder.
+Состояния `recording` и `paused` меняются при этих событиях; внутренний MediaRecorder
+может изменить состояние раньше. Повтор в уже достигнутом состоянии успешен,
+повтор ожидающей операции возвращает тот же promise, а противоположная операция
+до её завершения отклоняется. До завершения старта, во время остановки и после
+завершения или dispose эти операции отклоняются. Остановка из паузы разрешена.
+Остановка, ошибка и dispose отклоняют ожидающий pause/resume; обычная остановка
+при этом возвращает финальное видео.
+
+`finished` — стабильный promise с момента создания: он ждёт результата без команды
+остановки, разрешается при ручном или автоматическом завершении и отклоняется при
+ошибке или dispose. Повторные `stop()` возвращают тот же результат.
+`stopReason` равен `manual` или `duration-limit`; сохраняется причина первого запроса остановки.
+
+`maxDurationMs` проверяется до захвата и фиксируется при создании. Без него автоматической
+остановки нет. Бюджет считается от события start до pause и от resume до следующей
+паузы/остановки. Превышение вызывает обычную остановку с сохранением финального фрагмента.
+Из-за задержек таймеров, событий и кодирования это не покадрово точный предел файла;
+`durationMs` может оказаться больше лимита под нагрузкой.
+
+Исходные аудиодорожки и анимация продолжают работать во время паузы: их временной
+шкалой управляет приложение. Рекордер освобождает только принадлежащие ему дорожки
+захвата и аудиоклоны, таймеры, обработчики и накопленные фрагменты. Размер canvas
+должен оставаться постоянным и во время паузы.
+
+`examples/video.html` демонстрирует выбор формата, звук, паузу, продолжение,
+ручную/автоматическую остановку, превью и скачивание. Браузерные тесты записывают
+и воспроизводят WebM и поддерживаемый MP4 H.264/AAC, проверяют звук, исключение пауз
+и владение дорожками; неподдерживаемые кодеки явно пропускаются.
+
+[Проверка синхронизации видео и звука](../docs/video-recording.md) использует шесть
+вспышек/сигналов до и после двух пауз, независимое декодирование FFmpeg с временными
+метками контейнера и контрольную копию с намеренно задержанным звуком.
+FFmpeg используется только в инструментах разработки и не включается в библиотеку.
+
+Первые видеокадры могут предшествовать событию start, особенно при запуске аудиодвижка.
+Лимит активного времени не обрезает этот стартовый материал: длительность файла может
+включать дополнительное время запуска и завершения кодировщика.
+
 ## Запись с озвучкой
 
 Сведите звук в одну выходную дорожку Web Audio: несколько звуковых дорожек
@@ -139,6 +195,43 @@ CanvasTake клонирует дорожки при start и при заверш
 для завершения записи вызовите `recorder.stop()`. Окончание AudioBufferSource
 также не завершает выходную дорожку.
 
+## Контроллер офлайн-видео (с версии 0.5.0)
+
+`@grundyjs/canvas-take/video` содержит `createOfflineVideoExporter` и контракты
+подключаемых видео-/аудиокодировщиков и упаковщика контейнера. Отдельные импорты
+`/video/webcodecs` (`createWebCodecsVideoEncoder`), `/video/aac` (`createAacAudioEncoder`)
+и `/video/mp4` (`createMp4Muxer`) создают реальный **MP4 H.264 Baseline / AAC-LC**.
+Видео требует WebCodecs; AAC кодируется в отдельном Worker через встроенный
+libavcodec WASM, включая браузеры без нативного AAC-кодировщика. Подготовленный PCM
+необязателен. Файлы, задержка, обрезка и A/V проверяются независимым FFmpeg-декодером.
+
+```js
+import { createOfflineVideoExporter } from '@grundyjs/canvas-take/video';
+// options содержит video.encoder/config, необязательное подготовленное аудио и muxer.
+const exporter = await createOfflineVideoExporter(options);
+try {
+    drawFrame(0);
+    await exporter.addFrame(canvas, { timestampUs: 0, durationUs: 33_333 });
+    const result = await exporter.finish();
+} finally {
+    exporter.dispose();
+}
+```
+
+Временная шкала непрерывна и начинается с нуля, единица времени — целая микросекунда.
+Длительности кадров и позиции аудиосэмплов не зависят от скорости кодирования.
+Контроллер копирует входные данные, ограничивает очереди, последовательно передаёт
+пакеты упаковщику и освобождает свои адаптеры при успехе, ошибке и отмене.
+Политика несовпадения длительности аудио задаётся явно: ошибка либо обрезка/тишина.
+[Описание API и протокола](../docs/offline-video-api.md) включает владение ресурсами,
+flush, отмену и лимиты. [Реальные адаптеры и точность временной шкалы](../docs/offline-video-adapters.md)
+содержат рабочий пример API; [браузерный пример](../examples/offline-video.html) позволяет
+экспортировать, отменить и скачать MP4. Упаковщик округляет абсолютные границы кадров
+до шкалы 57 600 Гц: дробная частота и финальное удержание проверены без накопления
+ошибки. [AAC: задержка и число сэмплов](../docs/offline-aac.md) описывает проверку
+44,1/48 кГц, mono/stereo, priming и padding. Длительность представления MP4 исключает
+AAC padding; при выводе полных AAC-кадров в сырой PCM нужно применять конечную границу контейнера.
+
 ## Покадровый экспорт GIF
 
 Доступен с версии 0.3.0.
@@ -308,11 +401,66 @@ AlgiViz и не изменяет тот проект.
 `npm test` запускает модульные тесты и проверки Node Worker, а `npm run test:package`
 проверяет установку упакованной библиотеки в отдельный проект. Для настоящих браузеров
 сначала выполните `npx playwright install chromium firefox`, затем `npm run test:browser`.
-Проверяются GIF-экспорт, отмена, повторный экспорт на той же странице, завершение Worker
-и независимое декодирование результата. `npm run test:next` проверяет сборку
+Проверяются запись видео, офлайн MP4/AAC и GIF, отмена, повторный экспорт, освобождение
+ресурсов и независимое декодирование звука/временной шкалы. `npm run test:next` проверяет сборку
 упакованной библиотеки с Next.js/Turbopack. Подробности — в
 [описании проверок GIF](../docs/gif-encoder.md#verification).
 
+`npm run test:release-video` устанавливает tarball кандидата и из его ассетов экспортирует
+10-секундный MP4 H.264/AAC, 1080×1920. Проверяет все 300 декодированных кадров,
+480 000 аудиосэмплов представления, воспроизведение, размеры и четыре A/V-маркера.
+MP4 и метрики сохраняются в `test-results/release-video/`.
+
+Для сравнения производительности GIF-адаптеров выполните `npm run benchmark:gif`
+(короткий прогон: `npm run benchmark:gif -- --quick`). Матрица разрешений и длительностей,
+границы измерений и ограничения описаны в [методике бенчмарка](../docs/gif-benchmark.md).
+
+Команда `npm run benchmark:gif -- --compare-opacity` сравнивает код до оптимизации
+с текущим на непрозрачных кадрах, смешанной прозрачности и полупрозрачных градиентах.
+
+## Лимиты GIF (с версии 0.5.0)
+
+Пример `examples/gif.html` позволяет задать все три лимита. Значения по умолчанию
+соответствуют его анимации: 800×450 пикселей, 121 кадр и 8 000 мс с финальной паузой.
+Пустое поле отключает дополнительный лимит. При превышении пример объясняет, что
+увеличить, и возвращает настройки для повтора. Новый запуск убирает предыдущие
+ссылку скачивания и превью, чтобы старый результат не показывался после ошибки.
+
+В `createGifExporter` можно задать ограничения, одинаковые для синхронного и Worker-адаптеров:
+
+```js
+const gif = createGifExporter({
+    encoder: createGifWorkerEncoder(),
+    maxFramePixels: 1920 * 1080,
+    maxFrames: 600,
+    maxDurationMs: 30_000
+});
+try {
+    await gif.addFrame(canvas, 50);
+    const blob = await gif.finish();
+} catch (error) {
+    // При превышении лимита addFrame отклоняется с RangeError и именем лимита.
+    console.error(error);
+} finally {
+    gif.dispose();
+}
+```
+
+Каждое значение — положительное безопасное целое число. Без параметра дополнительного
+ограничения по нему нет; ограничения формата GIF сохраняются. Границы включительны:
+`maxFramePixels` ограничивает `width * height`, `maxFrames` — число успешно закодированных
+кадров, `maxDurationMs` — сумму длительностей после округления каждого кадра до 10 мс.
+Два кадра по 54 мс занимают 100 мс, кадр на 55 мс — 60 мс. Повторное воспроизведение
+не умножает длительность. `totalFrames` остаётся подсказкой для прогресса и не связан с `maxFrames`.
+
+Неверное значение вызывает `RangeError` при создании, до выделения кодировщика или Worker.
+При превышении лимита `addFrame` отклоняется до чтения пикселей и передачи кадра кодировщику.
+Экспортер переходит в конечное состояние `failed`, сообщает один снимок прогресса ошибки
+с ранее завершёнными кадрами, удаляет обработчик отмены и освобождает кодировщик, включая
+завершение принадлежащего ему Worker. Получить частичный GIF через `finish` после ошибки
+нельзя; для повтора нужен новый экспортер. Исходный canvas сохраняется. Лимиты ограничивают
+входную работу, но не задают точный предел памяти или размера файла.
+
 ## Выпуск версии
 
 Запустите `npm test` и `npm run test:package`: последняя команда упаковывает архив,