h264-parser

Full TypeScript H.264 bitstream parser for SPS/PPS/SEI and NAL units with complete type definitions and modern ES modules support.

Installation

# Using npm
npm install h264-parser

# Using pnpm
pnpm add h264-parser

# Using yarn
yarn add h264-parser

NALUnit includes: raw bytes (rawData), RBSP after removing emulation-prevention bytes (rbspData), header info, and optional parses for SPS/PPS/SEI/AUD/SLICE when available.

API

• parseH264AnnexB(data: Uint8Array): NALUnit[]
• parseH264AVC(data: Uint8Array): NALUnit[]

Usage Examples

Working with Sample Files

The repository includes sample H.264 files in examples/samples/:

• basic.h264 - Simple H.264 stream with SPS/PPS/IDR/SLICE
• complex.h264 - More complex stream with multiple GOPs

You can run the example script to see the parser in action:

# Using pnpm
pnpm run example

# Using npm
npm run example

This will parse both sample files and show detailed information about each NAL unit.

Parsing Different NAL Unit Types

import { H264Parser } from 'h264-parser';
import { readFileSync } from 'fs';

const parser = new H264Parser();
const data = readFileSync('examples/samples/basic.h264');
const nalus = parser.parseH264AnnexB(data);

// Find specific NAL unit types
const spsNalus = nalus.filter((nalu) => nalu.nalUnitType === 7); // SPS
const ppsNalus = nalus.filter((nalu) => nalu.nalUnitType === 8); // PPS
const idrNalus = nalus.filter((nalu) => nalu.nalUnitType === 5); // IDR
const sliceNalus = nalus.filter((nalu) => nalu.nalUnitType === 1); // P-slice

console.log(
  `SPS: ${spsNalus.length}, PPS: ${ppsNalus.length}, IDR: ${idrNalus.length}, Slices: ${sliceNalus.length}`
);

Extracting SPS Information

const spsNalu = nalus.find((nalu) => nalu.sps);
if (spsNalu?.sps) {
  const sps = spsNalu.sps;
  console.log(`Profile: ${sps.profileIdc}`);
  console.log(`Level: ${sps.levelIdc}`);
  console.log(`Width: ${sps.picWidthInMbs * 16}`);
  console.log(`Height: ${sps.picHeightInMbs * 16}`);
  console.log(`Frame Rate: ${sps.frameRate}`);
}

Generate .h264 samples with FFmpeg

You can produce raw H.264 elementary streams in Annex B format using FFmpeg.

• From an MP4 without re-encoding (bitstream copy to Annex B):

ffmpeg -i input.mp4 -c:v copy -an -bsf:v h264_mp4toannexb -f h264 output_basic.h264

• Re-encode with x264 and fixed keyframe interval (useful for testing IDR/GOP):

ffmpeg -i input.mp4 \
  -c:v libx264 -profile:v baseline -level 3.0 \
  -x264-params keyint=60:min-keyint=60:no-scenecut=1 \
  -an -f h264 output_gop60.h264

Both outputs are Annex B. Feed their bytes directly to parseH264AnnexB. If you have length-prefixed NAL units (e.g., from some container extractions), use parseH264AVC.

TypeScript Support

This library is built with TypeScript from the ground up and provides:

• ✅ Complete type definitions for all H.264 structures (SPS, PPS, SEI, Slice headers)
• ✅ Full IntelliSense support in VS Code and other TypeScript editors
• ✅ Type-safe API with comprehensive interfaces for all NAL unit types
• ✅ Modern ES modules with proper TypeScript exports
• ✅ Zero configuration - works out of the box with TypeScript projects

TypeScript Example

import { H264Parser, type NALUnit, type SPS, type PPS } from 'h264-parser'

const parser = new H264Parser()
const data = new Uint8Array([...]) // Your H.264 data
const nalus: NALUnit[] = parser.parseH264AnnexB(data)

// Full type safety and autocomplete
const spsNalu = nalus.find(nalu => nalu.sps)
if (spsNalu?.sps) {
  const sps: SPS = spsNalu.sps
  // TypeScript knows all available properties
  console.log(sps.profileIdc, sps.levelIdc, sps.picWidthInMbs)
}

License

MIT