threefive.js

JavaScript/TypeScript port of Python threefive — a SCTE-35 decoder for broadcast ad markers.

Decode-only. Synchronous. ESM. No dependencies.

import { Cue } from 'threefive-scte35';

const cue = new Cue('/DAvAAAAAAAA///wFAVIAACPf+/+c2nALv4AUsz1AAAAAAAKAAhDVUVJAAABNWLbowo=');

cue.command.name          // 'Splice Insert'
cue.command.ptsTime       // 21514.559089  (seconds)
cue.command.breakDuration // 60.293567     (seconds)
cue.descriptors[0].name   // 'Avail Descriptor'

Install

npm install threefive-scte35

Or reference a local clone:

"threefive-scte35": "^0.1.1"

Usage

From base64

import { Cue } from 'threefive-scte35';

const cue = new Cue('/DAvAAAAAAAA///wFAVIAACPf+/+c2nALv4AUsz1AAAAAAAKAAhDVUVJAAABNWLbowo=');

From hex

const cue = new Cue('0xFC302F000000000000FFFFF014054800008F7FEFFE7369C02EFE0052CCF5...');

From bytes

const cue = new Cue(new Uint8Array([0xfc, 0x30, ...]));

Inspect results

// Info section
cue.infoSection.tableId           // '0xfc'
cue.infoSection.spliceCommandType // 5
cue.infoSection.ptsAdjustment     // 0
cue.infoSection.crc               // '0x62dba30a'

// Splice command
cue.command.name          // 'Splice Insert'
cue.command.commandType   // 5
cue.command.ptsTime       // seconds (null if not specified)
cue.command.breakDuration // seconds (null if not a timed break)

// Descriptors
cue.descriptors           // SpliceDescriptor[]

Serialize to plain object

const obj = cue.get();
// {
//   info_section: { table_id: '0xfc', splice_command_type: 5, ... },
//   command: { name: 'Splice Insert', pts_time: 21514.559089, break_duration: 60.293567, ... },
//   descriptors: [{ name: 'Avail Descriptor', provider_avail_id: 309 }]
// }

API

new Cue(data?)

| Argument | Type | |---|---| | data | string \| Uint8Array \| undefined |

String inputs: hex (0xfc30... or fc30...) or base64. Uint8Array is passed directly. Passing nothing creates an empty instance.

The constructor calls decode() automatically.

cue.infoSection — SpliceInfoSection

| Property | Type | Notes | |---|---|---| | tableId | string \| null | Always '0xfc' | | sectionLength | number \| null | | | protocolVersion | number \| null | | | encryptedPacket | boolean \| null | | | ptsAdjustment | number | Seconds (90kHz converted) | | spliceCommandType | number \| null | | | spliceCommandLength | number \| null | | | descriptorLoopLength | number | | | crc | string \| null | Stored, not verified |

cue.command — splice command instances

| Class | commandType | Key fields | |---|---|---| | SpliceNull | 0 | — | | SpliceInsert | 5 | spliceEventId, ptsTime, breakDuration, breakAutoReturn, outOfNetworkIndicator, uniqueProgramId, availNum, availsExpected | | TimeSignal | 6 | ptsTime, timeSpecifiedFlag | | BandwidthReservation | 7 | — | | PrivateCommand | 255 | identifier, privateBytes |

ptsTime and breakDuration are in seconds (already divided by 90000). null when not present.

cue.descriptors — SpliceDescriptor[]

| Class | tag | Key fields | |---|---|---| | AvailDescriptor | 0 | providerAvailId | | DtmfDescriptor | 1 | preroll, dtmfCount, dtmfChars | | SegmentationDescriptor | 2 | segmentationEventId, segmentationTypeId, segmentationMessage, segmentationDuration, segmentationUpid, segmentNum, segmentsExpected | | TimeDescriptor | 3 | taiSeconds, taiNs, utcOffset | | PrivateDescriptor | any other | privateData |

SegmentationDescriptor segmentation types (table 22)

Common values:

| segmentationTypeId | segmentationMessage | |---|---| | 0x10 | Program Start | | 0x11 | Program End | | 0x20 | Chapter Start | | 0x21 | Chapter End | | 0x22 | Break Start | | 0x23 | Break End | | 0x30 | Provider Advertisement Start | | 0x31 | Provider Advertisement End | | 0x34 | Provider Placement Opportunity Start | | 0x35 | Provider Placement Opportunity End | | 0x36 | Distributor Placement Opportunity Start | | 0x37 | Distributor Placement Opportunity End |

Full table in src/segmentation.ts.

UPID types

segmentationUpid is a UpidResult:

{
  upidType: 8,
  upidTypeName: 'AiringID',
  upidLength: 8,
  upidValue: '0x2ca0a18a'
}

Supported: No UPID, AdID, UMID, ISAN, TID, AiringID, ADI, EIDR, ATSC, MPU, MID, ADS Info, URI, UUID, SCR.

Named exports

import {
  Cue,
  SpliceInfoSection,
  SpliceNull, SpliceInsert, TimeSignal, BandwidthReservation, PrivateCommand,
  AvailDescriptor, DtmfDescriptor, SegmentationDescriptor, TimeDescriptor,
  PrivateDescriptor, spliceDescriptor,
  Bitn,
  table20, table22, SUB_SEG_TYPES,
  decodeUpid,
} from 'threefive-scte35';

Design notes

• Decode-only. No encoding, no XML, no CRC generation.
• Synchronous. new Cue(data) returns immediately — no async init.
• BigInt bit reader. Bitn stores the input as one BigInt and slices bits without alignment constraints, matching Python's arbitrary-precision integer approach.
• Seconds throughout. ptsTime and breakDuration are divided by 90000 at parse time. No raw ticks exposed.
• ESM only. Targets ES2020 with "type": "module".

Relationship to Python threefive

This is a port of the decode path from superkabuki/threefive_is_scte35. Field names and class structure follow the Python library closely so output is comparable. The test suite cross-checks all parsed values against Python cue.show() output.

Not ported: encoding, XML output, CRC computation, HLS/DASH playlist parsing, network fetching.

License

MIT