@animax-js/animax-video

FFmpeg-based H.264/H.265 video decoder compiled to WebAssembly (WASM) for the AnimaX animation framework on the Web platform.

Features

• H.264 (AVC) and H.265 (HEVC) video decoding
• In-memory data input via custom AVIO callbacks (no file I/O)
• MP4/MOV container support through FFmpeg mov demuxer
• YUV420P / YUV422P / YUV444P pixel format output
• Minimal WASM binary size (~1.9 MB) through aggressive FFmpeg configuration

Installation

Install this package only when your AnimaX animation contains video layers. Keep its version aligned with @animax-js/animax.

npm install @animax-js/animax@latest \
  @animax-js/animax-video@latest

Usage

@animax-js/animax-video only provides the wasm URL. Load it through the core package before mounting <animax-view> instances that need video layer playback.

import { AnimaXViewElement } from '@animax-js/animax';
import { AnimaXVideoModuleUrl } from '@animax-js/animax-video';

const videoLoaded = await AnimaXViewElement.loadVideoModule(
  AnimaXVideoModuleUrl
);
if (!videoLoaded) {
  throw new Error('Failed to load AnimaX video module');
}

On the Web platform, video layers do not support ZIP-compressed video resources. Use JSON animations with accessible video resource URLs.

Package Contents

The npm package contains the prebuilt runtime files under out/; it does not include the source build scripts.

@animax-js/animax-video/
└── out/
    ├── index.js                  # JS entry (exports AnimaXVideoModuleUrl)
    ├── index.d.ts                # TypeScript declarations
    └── lib/
        └── animax-video.wasm     # WebAssembly decoder module (~1.9 MB)

Architecture

JavaScript / TypeScript
        │
        │  import { AnimaXVideoModuleUrl } from '@animax-js/animax-video'
        │  loadVideoModule(url) → fetch .wasm → WebAssembly.instantiate
        ▼
┌─────────────────────────────────┐
│   out/lib/animax-video.wasm      │  ← emcc -Oz -s SIDE_MODULE=1
│                                   │
│   namespace video_wasm {          │  C++ → WASM
│     CreateVideoDecoder()         │
│     DecodeFrame()               │
│     PrepareFrameData()           │
│     GetFrameData()              │
│   }                             │
│                                   │
│   Static libs (linked in):      │
│   ├── libavcodec.a  (h264+hevc) │
│   ├── libavformat.a (mov)   │
│   └── libavutil.a             │
└─────────────────────────────────┘

API (C ABI exported by WASM)

| Function | Description | |----------|-------------| | animax_video_decoder_alloc(data, size) | Create decoder from raw bytes | | animax_video_decoder_free(decoder) | Destroy decoder | | animax_video_prepare_frame_data(decoder, ...) | Extract all frame packets | | animax_video_frame_alloc(decoder, data, size) | Decode single frame | | animax_video_get_frame_data(frame, ...) | Read YUV plane data | | animax_video_frame_free(frame) | Release decoded frame |

FFmpeg Configuration

The FFmpeg static libraries are built with minimal configuration to minimize WASM size:

| Category | Enabled | |----------|---------| | Decoders | h264, hevc | | Demuxers | mov | | Parsers | h264, hevc | | Protocols | data | | Libraries | avcodec, avformat, avutil |

Everything else is disabled: encoders, muxers, filters, devices, swresample, swscale, network, hwaccels, pthreads, etc.

License

The AnimaX package materials are published under MIT terms.

This package also contains native video wrapper code built into out/lib/animax-video.wasm; the native wrapper source carries Apache-2.0 notices.

The WebAssembly module includes FFmpeg libraries linked into the binary. FFmpeg is distributed under LGPL-2.1-or-later by default. The recorded build did not enable --enable-gpl or --enable-nonfree.

Included compliance files:

• THIRD_PARTY_NOTICES.md
• LICENSES/LGPL-2.1-or-later.txt
• LICENSES/Apache-2.0.txt
• FFMPEG_SOURCE.md
• FFMPEG_BUILD_CONFIG.txt
• changes.diff
• REBUILD.md
• PATENTS.md

H.264/H.265/HEVC codec use may require separate patent licenses. This package does not grant patent rights.