Media recorder support (#511)

* feat: add MediaRecorder migration specification and outline new export workflows

* feat: implement RecordingService for video and audio processing

* feat: refactor VideoService to delegate audio and video conversion to RecordingService

* feat: add gifenc package

* feat: refactor VideoService to implement GIF encoding and improve error handling

* feat: migrate from VideoService to MediaExportService and remove FFmpeg dependencies

* feat: add setup script for Chromium installation for unit tests

* feat: refactor Animator and MediaExportService to streamline video creation and remove WebMWriter dependency

* chore: Remove FFmpeg WebAssembly core and worker script files to streamline the project and eliminate unused dependencies.

* fix: update comment in formatProgress method for clarity on progress capping

* refactor: enhance documentation in AnimatorService and MediaExportService for clarity and maintainability

* chore: remove unused .vscode entry from .gitignore and update mediarecorder migration spec to English

* feat: add production Docker Compose configuration for app service

* chore: remove tentative timeline section from mediarecorder migration spec

* refactor: improve file loading process and enhance error handling in Animator class

* feat: implement MediaImportService for handling media file imports and decoding

* chore: update packageManager version in package.json

* test: add unit tests for MediaImportService functionality

* feat: enhance MediaImportService to return video and audio blobs, refactor load method in Animator class

* refactor: update load method signatures in Animator and AnimatorService to use Blob type

* fix: improve error handling and refactor decodeFile method in Animator class

* fix: update handleFrame to accept blob and index parameters in Animator class

* feat: add ADR 0001 to enforce VP8 WebM exports for improved compatibility

* feat: implement frame manifest support in media import and animator services

Author: mgaebler

.gitignore

@@ -22,7 +22,6 @@ npm-debug.log*
 /.sass-cache
 /.sourcemaps
 /.versions
-/.vscode
 /coverage
 /dist
 /node_modules

README.md

@@ -42,3 +42,18 @@ yarn test
 
 - [Codec Documentation](docs/CODECS.md) - Information about image, video, and audio codecs used
 - [Third-Party Licenses](THIRD_PARTY_LICENSES.md) - License information for codec-related dependencies
+
+## Chromium setup for unit tests
+
+Karma runs the Angular unit tests inside ChromiumHeadless. If the container or host image does not already provide Chromium, run:
+
+```
+./scripts/setup-chromium.sh
+```
+
+After installation export `CHROMIUM_BIN` so Karma picks up the binary (add this to your shell profile if you run tests frequently):
+
+```
+export CHROMIUM_BIN=$(which chromium)
+npm run test
+```

THIRD_PARTY_LICENSES.md

@@ -4,22 +4,19 @@ This document lists third-party libraries and their licenses used in the StopCli
 
 ## Codec-Related Dependencies
 
-### FFmpeg.wasm (@ffmpeg/ffmpeg)
+### gifenc
 
-**Version:** 0.12.15  
+**Version:** 1.0.3  
 **License:** MIT License  
-**Purpose:** Used for video and audio encoding/decoding, format conversion  
-**Source:** https://github.com/ffmpegwasm/ffmpeg.wasm
-
-FFmpeg.wasm is a pure WebAssembly port of FFmpeg. It enables video & audio record, convert and stream right inside browsers.
+**Purpose:** Generates GIF animations client-side during export  
+**Source:** https://github.com/mattdesl/gifenc  
+**Author:** Matt DesLauriers
 
 **License Text:**
 
 ```
 MIT License
 
-Copyright (c) 2019 Jerome Wu
-
 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
@@ -39,34 +36,6 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 ```
 
-**Note:** FFmpeg.wasm uses libraries from the FFmpeg project under the LGPLv2.1. See https://ffmpeg.org for more information.
-
-### webm-writer
-
-**Version:** 1.0.0  
-**License:** WTFPL (Do What The Fuck You Want To Public License)  
-**Purpose:** Creates WebM videos from Canvas frames for draft saves  
-**Source:** https://github.com/thenickdude/webm-writer-js  
-**Author:** Nicholas Sherlock
-
-**License Text:**
-
-```
-DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE
-Version 2, December 2004
-
-Copyright (C) 2004 Sam Hocevar <sam@hocevar.net>
-
-Everyone is permitted to copy and distribute verbatim or modified
-copies of this license document, and changing it is allowed as long
-as the name is changed.
-
-DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE
-TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
-
-0. You just DO WHAT THE FUCK YOU WANT TO.
-```
-
 ### webm.js
 
 **License:** BSD Zero Clause License (BSD-0)  
@@ -105,7 +74,7 @@ The application uses the following codecs:
 
 ### Video Formats
 - **WebM:** Container format
-- **VP8:** Video codec (via libvpx in FFmpeg)
+- **VP8:** Video codec (via the browser's MediaRecorder implementation)
 - **VP9:** Not currently used but supported by modern browsers
 
 ### Audio Formats
@@ -125,7 +94,7 @@ All third-party licenses are compatible with the GNU Affero General Public Licen
 - **MIT License:** Permissive, GPL-compatible
 - **WTFPL:** Public domain equivalent, GPL-compatible
 - **BSD-0:** Permissive, GPL-compatible
-- **LGPLv2.1 (FFmpeg):** Compatible with AGPL through dynamic linking
+- **MIT License (gifenc):** Permissive and GPL-compatible
 
 ## Additional Dependencies
 

docker-compose.prod.yml

@@ -0,0 +1,8 @@
+services:
+  app:
+    build:
+      context: .
+      dockerfile: Dockerfile
+      target: production
+    ports:
+      - "${DOCKER_COMPOSE_APP_PORT_PUBLISHED:-8080}:8080"

docs/CODECS.md

@@ -26,18 +26,7 @@ this.imageCanvas.toBlob(async (blob: Blob) => {
 
 ### Internal Storage: WebP
 
-All frames are converted to **WebP** format for internal processing:
-
-```typescript
-await this.ffmpeg.exec([
-  "-i", inputPath,
-  "-c:v", "libwebp",
-  "-lossless", "0",
-  "-compression_level", "4",
-  "-quality", "65",
-  outputPath
-]);
-```
+All frames are converted to **WebP** format for internal processing using the browser's Canvas APIs. Frames that arrive as JPEG are decoded via `createImageBitmap`, rendered into an offscreen canvas, and saved back as WebP blobs for consistent downstream handling.
 
 **Rationale:**
 - Better compression than JPEG (25-35% smaller files)
@@ -50,7 +39,7 @@ await this.ffmpeg.exec([
 The application handles mixed JPEG/WebP frames intelligently:
 
 1. **Capture:** Frames are captured as JPEG from canvas
-2. **Storage:** JPEG frames are converted to WebP via FFmpeg for consistency
+2. **Storage:** JPEG frames are converted to WebP via Canvas for consistency
 3. **Export:** All frames are WebP when creating videos or GIFs
 4. **Import:** Loaded frames are stored as WebP internally
 
@@ -69,7 +58,7 @@ This approach ensures:
 All video outputs use the **WebM** container format:
 
 ```typescript
-const result = await this.videoService.createVideo(
+const result = await this.mediaExportService.createVideo(
   this.animator.frameWebpsAndJpegs,
   frameRate,
   this.animator.audioBlob,
@@ -84,27 +73,18 @@ const result = await this.videoService.createVideo(
 - Native HTML5 video element support
 - Good compression ratios
 
-### Video Codec: VP8 (libvpx)
+### Video Codec: VP8 (MediaRecorder)
 
-Video encoding uses **VP8** codec via FFmpeg:
-
-```typescript
-parameters.push(
-  "-vcodec", "libvpx",
-  "-vf", "scale=640:-2,format=yuv420p",
-  outputFileName
-);
-```
+Video encoding uses **VP8** via the browser's native MediaRecorder implementation. The recording pipeline renders frames onto an offscreen canvas, captures a `MediaStream` with `canvas.captureStream(frameRate)`, optionally merges an audio stream, and records with a VP8-capable MIME type (preferring `video/webm;codecs=vp9,opus` and falling back to `video/webm;codecs=vp8,opus`).
 
 **Rationale:**
-- Royalty-free
-- Broad browser support (Chrome 6+, Firefox 4+, Safari 14.1+, Edge 79+)
-- Good balance of quality and file size
-- Hardware acceleration available on most devices
+- Royalty-free and hardware-accelerated in modern browsers
+- Eliminates heavy WASM workers and virtual file systems
+- Seamlessly combines audio/video tracks via `MediaStream`
 
 **Video Processing Options:**
-- Scale to max width of 640px (maintains aspect ratio)
-- YUV 4:2:0 color space (standard for web video)
+- Scale to max width of 640px before rendering
+- YUV 4:2:0 color space is enforced by the browser implementation
 - Configurable frame rate (default: 6 fps for stop motion)
 
 ### Future Consideration: VP9
@@ -137,38 +117,15 @@ this.audioRecorder = new MediaRecorder(this.audioStream, {
 
 ### Storage: WebM/Opus
 
-Regardless of the recorder outcome, audio blobs are converted to **WebM/Opus**:
-
-```typescript
-await this.ffmpeg.exec([
-  "-i", inputAudioPath,
-  "-vn",
-  "-c:a", "libopus",
-  outputPath // .webm
-]);
-```
-
-**Rationale:**
-- Aligns with the WebM-based video pipeline
-- Opus is royalty-free and optimised for voice
+Regardless of the recorder outcome, audio blobs are normalized to **WebM/Opus** via an `AudioContext`. The export service decodes the blob, replays it through a `MediaStreamAudioDestination`, and records the result so downstream consumers always receive an Opus/WebM payload.
 
 ## GIF Export
 
-GIF creation uses FFmpeg with a two-pass palette approach:
-
-```typescript
-const gifParameters = [
-  "-r", `${frameRate}`,
-  "-i", inputPattern,
-  "-vf", `fps=${frameRate},scale=480:-1:flags=lanczos,split[s0][s1];[s0]palettegen[p];[s1][p]paletteuse`,
-  "-loop", "0",
-  outputFileName
-];
-```
+GIF creation uses the lightweight **gifenc** library. Frames are decoded, resized to a maximum width of 480px, quantized to an indexed palette, and encoded via gifenc's `GifEncoder`. Progress callbacks fire between batches so the UI can stay responsive.
 
 **Features:**
-- Palette generation for optimal colors
-- Lanczos scaling for quality
+- Deterministic palette building and dithering for good quality
+- Runs entirely on the client without WASM payloads
 - Scaled to 480px width for reasonable file size
 - Infinite loop by default
 
@@ -186,26 +143,9 @@ project.zip
 
 **Implementation:**
 - Uses @zip.js/zip.js library
-- Frames are encoded to WebM using webm-writer library
+- Video blobs originate from `MediaRecorder` (via MediaExportService)
 - Audio is stored separately if present
 
-### WebM Draft Format
-
-Draft videos are created using the webm-writer library:
-
-```typescript
-const videoWriter = new WebMWriter({
-  quality: 0.95,
-  frameRate: frameRate,
-  transparent: false
-});
-```
-
-**Rationale:**
-- Fast encoding in browser
-- Compatible with our import pipeline
-- No server-side processing required
-
 ## Browser Compatibility Matrix
 
 | Format | Chrome | Firefox | Safari | Edge |
@@ -238,7 +178,7 @@ The consistent use of WebM and WebP ensures:
 ### Memory Management
 
 1. **Batch Processing:** JPEG→WebP conversion is batched to prevent memory issues
-2. **Streaming:** FFmpeg processes frames in a temporary directory
+2. **Streaming:** MediaRecorder writes directly to in-memory blobs
 3. **Cleanup:** Working directories are cleaned up after processing
 
 ### Processing Time
@@ -256,15 +196,10 @@ Times vary based on:
 
 ## Dependencies
 
-### FFmpeg.wasm
-- **Purpose:** Video/audio encoding, format conversion
-- **License:** MIT (with LGPL FFmpeg libraries)
-- **Version:** 0.12.15
-
-### webm-writer
-- **Purpose:** Draft video creation
-- **License:** WTFPL
-- **Version:** 1.0.0
+### gifenc
+- **Purpose:** GIF encoding
+- **License:** MIT
+- **Version:** 1.0.3
 
 ### webm.js
 - **Purpose:** WebM container decoding
@@ -287,5 +222,4 @@ Times vary based on:
 ## Related Documentation
 
 - [Third-Party Licenses](../THIRD_PARTY_LICENSES.md)
-- [FFmpeg.wasm Documentation](https://ffmpegwasm.netlify.app/)
 - [WebM Container Specification](https://www.webmproject.org/docs/container/)