@amazon/vinyl-transmux 1.0.0

package/dist/types/ts4.7/aac/adts.d.ts

@@ -0,0 +1,38 @@
+/**
+ * ADTS (Audio Data Transport Stream) frame parser for AAC.
+ *
+ * ADTS is the framing format used to carry AAC audio in MPEG-TS and raw .aac
+ * files. Each frame starts with a 7-byte (or 9-byte with CRC) sync header
+ * containing the audio object type, sample rate, and channel configuration
+ * needed to construct the MP4 AudioSpecificConfig.
+ *
+ * @module
+ */
+export interface AdtsFrame {
+    /** Offset of this frame within the source buffer. */
+    readonly offset: number;
+    /** Total frame size including header. */
+    readonly frameLength: number;
+    /** Size of the ADTS header (7 or 9 bytes). */
+    readonly headerSize: number;
+    /** AAC audio object type (1 = AAC-LC, 2 = HE-AAC, etc.). */
+    readonly audioObjectType: number;
+    /** Sampling frequency index (0-12). */
+    readonly samplingFrequencyIndex: number;
+    /** Channel configuration (1 = mono, 2 = stereo, etc.). */
+    readonly channelConfiguration: number;
+}
+/**
+ * Returns the sample rate in Hz for a given sampling frequency index.
+ */
+export declare function adtsSampleRate(index: number): number;
+/**
+ * Parses all ADTS frames from a buffer of raw AAC data.
+ */
+export declare function parseAdtsFrames(data: Uint8Array): AdtsFrame[];
+/**
+ * Builds the AudioSpecificConfig (2 bytes) for an AAC-LC stream.
+ * This is required in the MP4 esds box.
+ */
+export declare function buildAudioSpecificConfig(frame: AdtsFrame): Uint8Array;
+//# sourceMappingURL=adts.d.ts.map

package/dist/types/ts4.7/index.d.ts

@@ -0,0 +1,7 @@
+/** Auto-generated from build scripts */
+export * from './transmux/transmux';
+export * from './transmux/sampleEntry';
+export * from './mpegts/mpegts';
+export * from './mp4/mp4';
+export * from './aac/adts';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/ts4.7/mp4/mp4.d.ts

@@ -0,0 +1,70 @@
+/** 90 kHz timescale from ISO 13818-1 (MPEG system clock). */
+export declare const MPEG_TIMESCALE = 90000;
+/**
+ * Writes a generic MP4 box (atom). The size field is automatically computed.
+ */
+export declare function box(type: string, ...payloads: Uint8Array[]): Uint8Array;
+/**
+ * Writes a full box with version and flags.
+ */
+export declare function fullBox(type: string, version: number, flags: number, payload: Uint8Array): Uint8Array;
+export interface FtypOptions {
+    readonly majorBrand?: string;
+    readonly minorVersion?: number;
+    readonly compatibleBrands?: readonly string[];
+}
+/**
+ * Generates the ftyp box.
+ */
+export declare function ftyp(options?: FtypOptions): Uint8Array;
+/**
+ * Generates a moov box from pre-built track boxes.
+ */
+export declare function moov(...traks: Uint8Array[]): Uint8Array;
+export interface MvhdOptions {
+    readonly timescale?: number;
+    readonly duration?: number;
+    readonly rate?: number;
+    readonly volume?: number;
+}
+export interface AudioTrackOptions {
+    readonly trackId: number;
+    readonly sampleRate: number;
+    readonly channelCount: number;
+    readonly sampleEntry: Uint8Array;
+}
+export interface VideoTrackOptions {
+    readonly trackId: number;
+    readonly width: number;
+    readonly height: number;
+    readonly timescale?: number;
+    readonly sampleEntry: Uint8Array;
+}
+export declare function audioTrak(options: AudioTrackOptions): Uint8Array;
+export declare function videoTrak(options: VideoTrackOptions): Uint8Array;
+export interface MoofOptions {
+    readonly sequenceNumber: number;
+    readonly trackId: number;
+    readonly baseDecodeTime: number;
+    readonly samples: readonly SampleEntry[];
+}
+export interface SampleEntry {
+    readonly duration: number;
+    readonly size: number;
+    readonly flags?: number;
+    readonly compositionTimeOffset?: number;
+}
+/**
+ * Generates a moof (movie fragment) box.
+ */
+export declare function moof(options: MoofOptions): Uint8Array;
+/**
+ * Generates an mdat box wrapping raw media data.
+ */
+export declare function mdat(data: Uint8Array): Uint8Array;
+/**
+ * Patches the trun data_offset field. The data_offset is the byte offset from
+ * the start of the moof to the first byte of the mdat payload.
+ */
+export declare function patchDataOffset(moofData: Uint8Array, moofSize: number): void;
+//# sourceMappingURL=mp4.d.ts.map

package/dist/types/ts4.7/mpegts/mpegts.d.ts

@@ -0,0 +1,68 @@
+/**
+ * MPEG-TS constants and packet-level parsing.
+ *
+ * An MPEG Transport Stream consists of fixed 188-byte packets. Each packet
+ * starts with a sync byte (0x47) and carries a 13-bit PID identifying the
+ * elementary stream. The PAT (PID 0) maps program numbers to PMT PIDs, and
+ * the PMT lists the elementary stream PIDs with their stream types.
+ *
+ * @module
+ */
+export declare const TS_PACKET_SIZE = 188;
+export declare const TS_SYNC_BYTE = 71;
+/** Well-known stream type identifiers from ISO/IEC 13818-1. */
+export declare const STREAM_TYPE_AAC = 15;
+export declare const STREAM_TYPE_H264 = 27;
+export declare const STREAM_TYPE_H265 = 36;
+export declare const STREAM_TYPE_ID3 = 21;
+export interface TsPacketHeader {
+    readonly pid: number;
+    readonly payloadUnitStartIndicator: boolean;
+    readonly adaptationFieldControl: number;
+    readonly continuityCounter: number;
+}
+export interface PmtEntry {
+    readonly pid: number;
+    readonly streamType: number;
+}
+/**
+ * Parses a single 188-byte TS packet header.
+ */
+export declare function parseTsPacketHeader(data: Uint8Array, offset: number): TsPacketHeader;
+/**
+ * Returns the offset of the payload within a TS packet.
+ */
+export declare function getPayloadOffset(data: Uint8Array, offset: number, adaptationFieldControl: number): number;
+/**
+ * Parses the PAT (Program Association Table) to find the PMT PID.
+ */
+export declare function parsePat(data: Uint8Array, offset: number): number;
+/**
+ * Parses the PMT (Program Map Table) to extract elementary stream entries.
+ */
+export declare function parsePmt(data: Uint8Array, offset: number): PmtEntry[];
+export interface DemuxedStream {
+    readonly streamType: number;
+    readonly pid: number;
+    readonly data: Uint8Array[];
+}
+/**
+ * Demuxes a complete MPEG-TS segment into elementary streams.
+ * Reassembles PES packets from TS packets for each PID.
+ */
+export declare function demuxTsSegment(segment: Uint8Array): DemuxedStream[];
+/**
+ * Concatenates an array of Uint8Arrays into a single Uint8Array.
+ */
+export declare function concatBuffers(buffers: Uint8Array[]): Uint8Array;
+/**
+ * Strips the PES header from raw PES packet data, returning the elementary
+ * stream payload.
+ */
+export declare function stripPesHeader(pesData: Uint8Array): Uint8Array;
+/**
+ * Extracts the PTS (Presentation Time Stamp) from a PES header.
+ * Returns the PTS in 90kHz clock ticks, or -1 if not present.
+ */
+export declare function parsePesPts(pesData: Uint8Array): number;
+//# sourceMappingURL=mpegts.d.ts.map

package/dist/types/ts4.7/transmux/sampleEntry.d.ts

@@ -0,0 +1,25 @@
+export interface AudioTrackConfig {
+    readonly audioObjectType: number;
+    readonly samplingFrequencyIndex: number;
+    readonly channelConfiguration: number;
+    readonly sampleRate: number;
+    readonly audioSpecificConfig: Uint8Array;
+}
+export interface VideoTrackConfig {
+    readonly width: number;
+    readonly height: number;
+    readonly sps: Uint8Array;
+    readonly pps: Uint8Array;
+    readonly profileIdc: number;
+    readonly profileCompatibility: number;
+    readonly levelIdc: number;
+}
+/**
+ * Builds an mp4a sample entry box for AAC audio.
+ */
+export declare function mp4aSampleEntry(config: AudioTrackConfig): Uint8Array;
+/**
+ * Builds an avc1 sample entry box for H.264 video.
+ */
+export declare function avc1SampleEntry(config: VideoTrackConfig): Uint8Array;
+//# sourceMappingURL=sampleEntry.d.ts.map

package/dist/types/ts4.7/transmux/transmux.d.ts

@@ -0,0 +1,17 @@
+export interface TransmuxResult {
+    /** The initialization segment (ftyp + moov). Always present. */
+    readonly initSegment: ArrayBuffer;
+    /** The media segment (moof + mdat). */
+    readonly mediaSegment: ArrayBuffer;
+    /** Duration of this segment in seconds. */
+    readonly duration: number;
+}
+/**
+ * Creates a stateful transmuxer instance. Call `transmux()` for each HLS
+ * segment in order. The init segment is always returned (cached after first
+ * call).
+ */
+export declare function createTransmuxer(): {
+    transmux: (data: ArrayBuffer) => TransmuxResult;
+};
+//# sourceMappingURL=transmux.d.ts.map

package/docs/TRANSMUX.md

@@ -0,0 +1,131 @@
+# Transmux
+
+Converts MPEG-TS and raw ADTS segments into fragmented MP4 (fMP4) for playback
+via Media Source Extensions. Zero external dependencies.
+
+## Architecture
+
+The package is split into three layers:
+
+```
+┌─────────────────────────────────────────────┐
+│  transmux      Stateful transmuxer          │
+│                (createTransmuxer)           │
+├─────────────────────────────────────────────┤
+│  sampleEntry   Codec-specific MP4 boxes     │
+│                (mp4a/esds, avc1/avcC)       │
+├──────────────────┬──────────────────────────┤
+│  mp4             │  mpegts / adts           │
+│  Generic fMP4    │  Demux + parse           │
+│  box writer      │                          │
+└──────────────────┴──────────────────────────┘
+```
+
+- **mp4** — Generic ISO BMFF box writer. Produces `ftyp`, `moov`, `moof`,
+  `mdat`, and all structural sub-boxes. No codec knowledge. Configurable via
+  options with sensible defaults.
+- **mpegts** — MPEG Transport Stream demuxer. Parses PAT/PMT, reassembles PES
+  packets, extracts PTS timestamps.
+- **adts** — Audio Data Transport Stream parser. Extracts AAC frame boundaries,
+  sample rates, and channel configuration.
+- **sampleEntry** — Codec-specific MP4 sample entry builders. Produces `mp4a` +
+  `esds` for AAC and `avc1` + `avcC` for H.264. This is the only layer with
+  codec knowledge.
+- **transmux** — Stateful orchestrator. Detects the input format (MPEG-TS or raw
+  ADTS), demuxes, parses codec configuration, builds the fMP4 init and media
+  segments.
+
+## Usage
+
+```typescript
+import { createTransmuxer } from '@amazon/vinyl-transmux'
+
+const transmuxer = createTransmuxer()
+
+// For each HLS segment (ArrayBuffer of MPEG-TS or ADTS data):
+const result = transmuxer.transmux(segmentData)
+
+// result.initSegment — ftyp + moov (always returned, cached after first call)
+// result.mediaSegment — moof + mdat
+// result.duration — segment duration in seconds
+```
+
+The transmuxer is stateful — call `transmux()` for each segment in order. It
+tracks decode timestamps, sequence numbers, and codec configuration across
+calls. The init segment is generated on the first call and cached for subsequent
+calls.
+
+## Supported Formats
+
+| Input              | Output                          | Status |
+| ------------------ | ------------------------------- | ------ |
+| ADTS AAC           | fMP4 audio (`mp4a`)             | ✅     |
+| MPEG-TS with AAC   | fMP4 audio (`mp4a`)             | ✅     |
+| MPEG-TS with H.264 | fMP4 video (`avc1`)             | ✅     |
+| MPEG-TS muxed      | fMP4 video + audio (multi-trak) | ✅     |
+
+## MP4 Box Writer
+
+The `mp4` module is a general-purpose fMP4 box writer, usable independently of
+the transmuxer:
+
+```typescript
+import {
+    box,
+    fullBox,
+    ftyp,
+    moov,
+    audioTrak,
+    videoTrak,
+    moof,
+    mdat,
+    patchDataOffset,
+} from '@amazon/vinyl-transmux'
+
+// Custom ftyp
+const ftypBox = ftyp({
+    majorBrand: 'dash',
+    compatibleBrands: ['iso6', 'mp41'],
+})
+
+// Build a moov with custom tracks
+const moovBox = moov(
+    audioTrak({
+        trackId: 1,
+        sampleRate: 44100,
+        channelCount: 2,
+        sampleEntry: myAudioSampleEntry,
+    }),
+    videoTrak({
+        trackId: 2,
+        width: 1920,
+        height: 1080,
+        sampleEntry: myVideoSampleEntry,
+    })
+)
+
+// Build a media fragment
+const moofBox = moof({
+    sequenceNumber: 1,
+    trackId: 1,
+    baseDecodeTime: 0,
+    samples: [
+        { duration: 1024, size: 400 },
+        { duration: 1024, size: 380 },
+    ],
+})
+patchDataOffset(moofBox, moofBox.byteLength)
+const mdatBox = mdat(rawMediaData)
+```
+
+## ID3 Tags
+
+Leading ID3v2 tags (common in HLS for timed metadata) are automatically skipped
+before format detection.
+
+## H.264 SPS Parsing
+
+The transmuxer includes a minimal H.264 SPS parser that extracts resolution and
+profile information from Sequence Parameter Set NAL units. It supports Baseline,
+Main, and High profiles including the chroma format and scaling matrix
+extensions.

package/package.json

@@ -0,0 +1,82 @@
+{
+    "name": "@amazon/vinyl-transmux",
+    "version": "1.0.0",
+    "description": "MPEG-TS to fMP4 transmuxer for browser and Node.",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/amazonmusic/vinyl.git"
+    },
+    "license": "UNLICENSED",
+    "module": "./dist/index.js",
+    "main": "./dist/index.cjs",
+    "types": "./dist/types/ts3.7/index.d.ts",
+    "type": "module",
+    "sideEffects": [
+        "**/polyfill/**",
+        "test/**/*"
+    ],
+    "files": [
+        "dist/*",
+        "docs/*"
+    ],
+    "typesVersions": {
+        ">=5.4": {
+            "*": [
+                "./dist/types/current/index.d.ts"
+            ]
+        },
+        ">=4.7": {
+            "*": [
+                "./dist/types/ts4.7/index.d.ts"
+            ]
+        },
+        ">=4.1": {
+            "*": [
+                "./dist/types/ts4.1/index.d.ts"
+            ]
+        },
+        ">=3.7": {
+            "*": [
+                "./dist/types/ts3.7/index.d.ts"
+            ]
+        }
+    },
+    "exports": {
+        ".": {
+            "types@>=5.4": "./dist/types/current/index.d.ts",
+            "types@>=4.7": "./dist/types/ts4.7/index.d.ts",
+            "require": "./dist/index.cjs",
+            "import": "./dist/index.js"
+        }
+    },
+    "scripts": {
+        "analyzeExports": "tsx buildSrc/analyzeExports.ts",
+        "analyzeExports:write": "tsx buildSrc/analyzeExports.ts --write",
+        "clean": "rimraf --glob dist .eslintcache \"**/*.tsbuildinfo\"",
+        "indexFiles:check": "tsx buildSrc/writeIndexFiles.ts --check",
+        "indexFiles:write": "tsx buildSrc/writeIndexFiles.ts",
+        "build": "tsx buildSrc/build.ts",
+        "build:release": "tsx buildSrc/build.ts --release",
+        "prettier:check": "prettier . --ignore-path ../../.prettierignore --cache --check",
+        "prettier:write": "prettier . --ignore-path ../../.prettierignore --cache --write",
+        "eslint:check": "eslint . --cache --max-warnings=0",
+        "eslint:write": "eslint . --cache --fix",
+        "lint": "npm run indexFiles:check && npm run eslint:check && npm run prettier:check",
+        "lint:write": "npm run indexFiles:write && npm run eslint:write && npm run prettier:write",
+        "validate": "npm run lint && npm run test",
+        "test": "tsx --tsconfig ../../tsconfig.flat.json ../../node_modules/jasmine/bin/jasmine --config=test/unit/jasmine.config.json",
+        "test:coverage": "c8 npm run test",
+        "watch": "tsx buildSrc/build.ts --watch",
+        "watch:release": "tsx buildSrc/build.ts --watch --release"
+    },
+    "devDependencies": {
+        "@amazon/vinyl-build-utils": "^1.0.0",
+        "@amazon/vinyl-jasmine-wrapper": "^1.0.0"
+    },
+    "dependencies": {
+        "@amazon/vinyl-util": "^1.0.0"
+    },
+    "browserslist": [
+        "defaults, chrome 52, firefox 54, edge 15, safari 8"
+    ]
+}