v0.4.0

🚀 Release v0.4.0 : Video Pipeline Encoding and Scaling Updates

This release updates the foundational FFmpeg parameter boundaries and scaling filters to improve visual quality during Adaptive Bitrate (ABR) processing. The changes focus exclusively on x264/x265 rate control, chroma subsampling accuracy, and IO thread starvation mapping.

1. Rate Control and Adaptive Quantization

Default libx264 and libx265 rate control properties have been overridden with explicit flags to optimize VBR (Variable Bitrate) allocations across complex scene boundaries.

• Adaptive Quantization: Forced aq-mode=3 in both x264 and x265 profiles to bias bits towards dark scenes, reducing macroblocking.
• Intra Smoothing: explicitly passed no-strong-intra-smoothing=1 in HEVC (x265) to prevent detail loss in static 4K textures.
• Deblocking: Adjusted standard deblock limits to -2,-2 (HEVC) and -1,-1 (AVC) to prioritize sharpness over synthetic smoothing.
• Lookahead Depth: Abstracted lookahead frame thread evaluation into the .env boundary. Operators can now map X265_RC_LOOKAHEAD (default 40) and X264_RC_LOOKAHEAD (default 60). This forces the encoder to buffer more frames before making block decisions, trading memory footprint for higher PSNR targets.

2. Spatial Scaling and Chroma Subsampling

The downscaling graph for generating the ABR ladder has been modified to handle high-bitrate 10-bit YUV 4:2:0 sources without generating color shifts.

• Filter Switch: Deprecated the lanczos scaler in favor of spline.
• Chroma Accuracy: Injected accurate_rnd and full_chroma_int into the scale filter string. This enforces strict mathematical rounding on the chroma planes during spatial reduction, preventing color banding algorithms from breaking the Rec.2020/Rec.709 transfer characteristics.

3. Muxer Threading and Memory Sizing

Addressed a system performance ceiling where multiplexing overhead (fMP4 fragmentation) blocked the encoding computation threads.

• Queue Limits: Pushed -max_muxing_queue_size into the libavformat container config, mapping dynamically to a new MAX_MUXING_QUEUE_SIZE (default 4096) property. This prevents thread starvation.
• CMAF Structs: Added the +write_colr manifest flag when building the -f hls output. This forces color metadata boxes into the fragment headers, enforcing strict CMAF standard compliance for downstream CDNs.

4. Domain Boundary Types

Applied strict JSDoc schematics across the src/domain and src/infrastructure/ffmpeg boundaries.

• Type Safety: Formalized JobData, ProbeResult, and TranscodeResult.
• Adapter Documentation: Added implementation details to FFmpegAdapter methods detailing the exact behavior of libavformat container parsing and ITU-R standard audio downmixing (LFE zero-fold).

What's Changed

• [ HotFix ] : v0.3.1 remove x265 film tune by @maulik-mk in #21
• [ HotFix ] : v0.3.2 fix memory leak by @maulik-mk in #22
• [ Release ] : v0.4.0 by @maulik-mk in #28

Full Changelog: v0.3.0...v0.4.0

v0.3.0

🚀 Release v0.3.0 : High Dynamic Range (HDR) and Advanced ABR Ladders

(Date: March 2026)

This release introduces comprehensive HDR support and strict JSON-based encoding ladders, mapping source colorimetry directly to target fragment streams.

1. HDR and Dolby Vision Profiles

Restructured the encoding boundary to evaluate ffprobe color telemetry and pass exact matrix transforms into x265.

• Transfer Characteristics: Implemented arib-std-b67 for HLG and smpte2084 for PQ boundaries.
• Color Matrices: Enforces bt2020nc and yuv420p10le primitive bounds on all main10 tier executions.
• Profile Mapping: Introduced discrete JSON ladders for avc.sdr, hvc.sdr, hvc.pq, and dvh.pq (Dolby Vision Profile 8/10 bounds).

2. Audio Track Formatting

• Audio Track Mapping: Decoupled libfdk_aac stream commands from the video loop. Independent variants are now multiplexed into discrete CMAF streams per language tag (und, eng).

3. Fragment Segment Architecture

• Manifest Filename Generation: Shifted from static video_segment_name references to dynamically interpolated patterns (data_%03d.m4s, [videoId]_audio_[language]--%d.m4s).
• Base URL Injection: Enabled #EXT-X-STREAM-INF mapping to direct relative paths (e.g., passing CDN base prefixes) during manifest assembly.

Welcome to v0.3.0! This release represents a massive architectural leap forward for our video encoding infrastructure. We've completely moved away from VMAF in favor of a much more robust Adaptive Bitrate (ABR) system, and we've shipped some serious performance boosts for Azure storage.

Here is what's new and what's changed from v0.2.0:

The Big Shift: Goodbye VMAF, Hello ABR

We've officially migrated from VMAF to a standardized Adaptive Bitrate (ABR) architecture. Moving to ABR gives us much more predictable, consistent, and structured control over our video quality and encoding profiles.

We've introduced dedicated ABR JSON configuration profiles giving you out-of-the-box support for:

• HEVC (H.265) & Dolby Vision (DVH): For cutting-edge HDR content.
• AVC SDR: For rock-solid standard definition playback.
• Dedicated Audio Profiles: To ensure the sound scales perfectly with the video.

Multi-Core FFmpeg Scaling

Under the hood, we've overhauled our FFmpeg flag generation and profile logic. Your encoding jobs are no longer constrained by older single-thread configurations. Going forward, FFmpeg will smartly scale to maximize all available CPU cores, dramatically slashing the time it takes to encode heavy media.

CDN & HLS Streaming

We've fine-tuned the HLS manifest generator. It now outputs crystal-clear absolute URL paths. This means your streaming playback experience will be much more resilient and less susceptible to breaking when placed behind a CDN or proxy.

Azure Storage: Faster & More Secure

• Blazing Fast Uploads: We completely rewrote the Azure uploader to process files concurrently. Instead of uploading chunks one by one, your processed files are now dispatched in parallel batches (AZURE_UPLOAD_BATCH_SIZE), leading to much faster completion times.

🛠️ Database Testing Improvements

We've updated our local test suites to drop outdated SSL configurations (rejectUnauthorized) for Postgres and implemented smarter timeout limits to keep test suites running safely without hanging.

#17

@maulik-mk

v0.2.0

🚀 Release v0.2.0 : Core Architectural Engine and Queue IO

(Date: March 2026)

This build establishes the primary Node.js runtime infrastructure, replacing simple scripts with a strict Domain-Driven Design (DDD) boundary and distributed state machines.

1. Queue and Postgres Infrastructure

• BullMQ Integration: Deployed a persistent Redis-backed worker layer via BullMQ (video.worker.ts), providing retry mechanics and backoff telemetry.
• State Persistence: Introduced standard PostgreSQL mappings (src/infrastructure/db) for state machine locks (queued, processing, failed, completed).

2. FFmpeg Execution Adapter

• Child Process Wrapper: Implemented src/infrastructure/ffmpeg/core/runner.ts to manage non-blocking, asynchronous spawn() calls to the native binary.
• Progress Telemetry: Built stderr parsing heuristics to yield accurate timecode conversion metrics for upstream queue percentage visualization.
• HLS Pipeline Orchestration: Merged raw byte-stream definitions into a multi-tiered pipeline mapping (hls/pipeline.ts), routing output segments natively to tmpfs blocks.

3. Cloud Storage Bindings

• Azure SDK: Implemented uploadHLS via the StorageProvider interface (azure.service.ts), mapping local fragment arrays directly into container blobs with strict MIME type enforcement.

This release represents a significant architectural leap from v0.1.0, transforming the FFmpeg Worker from a basic script into a production-grade, distributed video processing engine.

Highlights (Since v0.1.0)

Complete Domain-Driven Design (DDD) Refactor

The codebase has been entirely restructured into a modular, testable DDD architecture.

• Separation of Concerns: Business logic is now isolated from infrastructure (FFmpeg, Storage, Queue).
• Extensibility: The new structure allows for easy addition of new codecs, storage providers, and processing steps.

Smart Per-Title Bitrate Adaptation (VMAF)

We've integrated Netflix's VMAF model to move beyond static bitrates.

• AI-Driven Quality: The worker now probes each video to mathematically determine the lowest bitrate that maintains a high perceptive quality (VMAF score > 95).
• Efficiency: Reduces storage and bandwidth costs up to 40% without sacrificing visual quality.

Robust HLS Encoding Pipeline

A new multi-phase HLS pipeline has been implemented for high reliability.

• Segmented Processing: Audio, H.264, and H.265 (HDR/SDR) are processed in sequential phases to optimize memory usage.
• Master Playlist Generation: Automatically generates adaptive bitrate (ABR) master playlists with precise stream mapping.

Enterprise Scale Infrastructure

• Azure Blob Storage: High-performance HLS segment uploads with parallel processing.
• BullMQ Distributed Workers: Redis-backed distributed queueing for reliable job handling at scale.
• Fastify API: A lightweight, high-performance server for worker health and job management.

Infrastructure & DevX

• FFmpeg 7.0 Support: Updated to use the latest FFmpeg features and optimizations.
• Dockerized CI/CD: Improved development workflow with standardized build scripts and automated E2E tests.
• Permission Reliability: Standardized execution permissions for all CI tools and scripts.

---

Core Stack Update: Node.js 24+, FFmpeg 7.1, libvmaf v0.6.1.

#13

@maulik-mk

v0.1.0

🚀 Release v0.1.0 : Containerization and CI Baseline

(Date: February 2026)

Initial commit to establish the CI sandbox and OS dependencies.

• Docker Execution Map: Implemented foundational Dockerfile pulling compiled libx264 and libx265 via Alpine/Ubuntu builder stages.
• Test Harness: Created ffmpeg.test.sh for evaluating binary compliance and verifying IO file operations.
• GitHub Actions: Bound standard pull-request linting and branch tagging CI workflows.

This release introduces a highly optimized, security-hardened FFmpeg worker image designed specifically for constrained cloud environments

Architecture & Optimization

• Multi-Stage Build Strategy: Utilizes a heavy builder stage (Alpine + GCC/Make) to compile from source, then copies only the resulting binaries to a pristine runtime image.
• Static Linking: FFmpeg is compiled with specific flags (--enable-static, --disable-shared) to minimize external dependencies.
• Binary Stripping: All debugging symbols and non-essential metadata have been stripped to reduce binary size.
• Zero-Bloat Philosophy: Removed all non-critical libraries (X11, SDL, device inputs, network tools) to minimize attack surface and image size.

Performance

• Target Environment: 1 vCPU / 1GB RAM.
• Memory Footprint: < 300MB peak usage during 4K -> 720p transcoding.
• Output: ~64MB compressed image size (vs ~300MB+ for standard jrottenberg/ffmpeg).

Capabilities

• Video: H.264 (libx264) with ultrafast preset optimization.
• Audio: AAC (libfdk_aac) for high-efficiency audio encoding.
• Streaming: Native support for HLS playlist generation (H.264/AAC segments).

Security

• Non-Root Execution: Runs as unprivileged.
• Read-Only Root Filesystem: Compatible, with writable permissions restricted to /output.

#8

@maulik-mk