HLS Ad Inserter

This project provides a tool to parse HLS m3u8 manifests and insert EXT-X-DATERANGE tags for ad breaks (Preroll, Midroll, Postroll). It uses the hls-parser library.

Installation

npm install

Testing

Run the test suite with AVA:

npm test

This runs 41 tests covering:

• Preroll, midroll, and postroll ad insertion
• Multiple ad breaks and sequential IDs
• Custom metadata and SCTE-35 attributes
• Edge cases (single segment, zero duration, variable durations)
• Error handling (master playlist rejection, missing parameters)

Usage

The main script index.js demonstrates how to use the transform function to insert ads into a sample manifest.

node index.js

This will generate output.m3u8 with the inserted ad breaks.

API

transform(manifestContent, adBreaks)

Parses an HLS manifest string and inserts ad breaks.

Parameters:

• manifestContent (string): The content of the m3u8 file.
• adBreaks (Array): An array of ad break configurations.

AdBreak Interface:

/**
 * @typedef {Object} AdBreak
 * @property {'preroll' | 'midroll' | 'postroll'} type - The type of ad break.
 * @property {number} duration - Duration of the ad break in seconds.
 * @property {number} [start] - Start time offset in seconds (required for midroll).
 * @property {Object} [metadata] - Additional attributes for EXT-X-DATERANGE (e.g., SCTE35-OUT).
 */

Returns:

• (string): The modified HLS manifest content.

Example

CommonJS

const fs = require('fs');
const { transform } = require('./src/transformer');

const content = fs.readFileSync('sample.m3u8', 'utf8');

const adBreaks = [
  { type: 'preroll', duration: 30 },
  { type: 'midroll', duration: 15, start: 20 },
  { type: 'postroll', duration: 30 }
];

const output = transform(content, adBreaks);
fs.writeFileSync('output.m3u8', output);

ES6 / TypeScript

import * as fs from 'fs';
import { transform } from './src/transformer';
import { AdBreak } from './src/types';

const content = fs.readFileSync('sample.m3u8', 'utf8');

const adBreaks: AdBreak[] = [
  { type: 'preroll', duration: 30 },
  { type: 'midroll', duration: 15, start: 20 },
  { type: 'postroll', duration: 30 }
];

const output = transform(content, adBreaks);
fs.writeFileSync('output.m3u8', output);