@molecule/api-media-streaming-hls 1.0.0

package/LICENSE

@@ -0,0 +1,115 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work.
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship.
+
+      "Contribution" shall mean any work of authorship, including the
+      original version of the Work and any modifications or additions
+      to that Work, that is intentionally submitted to the Licensor for
+      inclusion in the Work by the copyright owner or by an individual or
+      Legal Entity authorized to submit on behalf of the copyright owner.
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by the Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      patent license to make, have made, use, offer to sell, sell, import,
+      and otherwise transfer the Work.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file.
+
+   5. Submission of Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND.
+
+   8. Limitation of Liability. In no event and under no legal theory shall
+      any Contributor be liable to You for damages.
+
+   9. Accepting Warranty or Additional Liability.
+
+   Copyright 2026 Molecule Dev, Inc.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/dist/browser-guard.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=browser-guard.d.ts.map

package/dist/browser-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-guard.d.ts","sourceRoot":"","sources":["../src/browser-guard.ts"],"names":[],"mappings":"AAuBA,OAAO,EAAE,CAAA"}

package/dist/browser-guard.js

@@ -0,0 +1,18 @@
+/**
+ * Browser guard — `@molecule/api-media-streaming-hls` is SERVER-ONLY.
+ *
+ * Generated by scripts/gen-browser-guards.mjs (workspace root) — edit THAT, not this.
+ * Evaluating a server package in a browser bundle is always an import-graph mistake
+ * (node APIs, secrets); without this guard it surfaces as a cryptic downstream crash
+ * ("Buffer is not defined") far from the culprit. Throwing here names the package and
+ * the fix at the exact moment the client bundle evaluates it. jsdom tests and SSR are
+ * unaffected: the throw requires browser globals AND the absence of a node runtime.
+ */
+const g = globalThis;
+if (g.window !== undefined && g.document !== undefined && !g.process?.versions?.node) {
+    throw new Error('@molecule/api-media-streaming-hls is SERVER-ONLY: it was bundled into browser/client code. Import it only ' +
+        'from server code (a server route/function or your API), or dynamic-import it inside ' +
+        'the server handler — never from components or shared client modules, and never ' +
+        'polyfill Buffer/process to silence this.');
+}
+export {};

package/dist/index.d.ts

@@ -0,0 +1,48 @@
+/**
+ * HLS media streaming provider for molecule.dev.
+ *
+ * Provides HLS (HTTP Live Streaming) support via ffmpeg for media segmentation
+ * and transcoding, with pure-TypeScript M3U8 playlist generation. Requires
+ * ffmpeg to be installed on the host system.
+ *
+ * @example
+ * ```typescript
+ * import { setProvider, createStream } from '@molecule/api-media-streaming'
+ * import { provider } from '@molecule/api-media-streaming-hls'
+ *
+ * setProvider(provider)
+ *
+ * const manifest = await createStream('/path/to/video.mp4', {
+ *   segmentDuration: 6,
+ *   protocol: 'hls',
+ * })
+ * console.log(manifest.manifestUri) // '/hls-…/index.m3u8'
+ * ```
+ *
+ * @remarks
+ * - **Requires the `ffmpeg` binary on the host** (resolved via PATH, or set
+ *   `createProvider({ ffmpegPath })`). A missing binary fails at first
+ *   `createStream()`/`transcode()` call with `spawn ffmpeg ENOENT` — verify
+ *   with `ffmpeg -version` before shipping.
+ * - **The default output directory is `os.tmpdir()`** — volatile and served by
+ *   nothing. Pass `createProvider({ outputBasePath })` pointing at a directory
+ *   your server exposes (see the core remarks), or serve bytes through
+ *   `getSegment()` / `generateManifest()` endpoints.
+ * - `createStream()` also caches every segment `Buffer` in an in-process map
+ *   (never evicted) so `getSegment()` is fast; memory grows by the full video
+ *   size per stream. `getSegment()` disk fallback looks ONLY under
+ *   `outputBasePath/<streamId>/` — a per-call `createStream(..., { outputPath })`
+ *   override writes segments where the fallback cannot find them after a
+ *   restart, and `transcode()` ignores `outputPath` entirely (always writes
+ *   under `outputBasePath`).
+ * - `ffprobePath` in `HlsConfig` is currently RESERVED — no ffprobe call exists
+ *   yet; segment durations come from the requested `segmentDuration`.
+ *
+ * @module
+ */
+export * from './browser-guard.js';
+export * from './m3u8.js';
+export * from './provider.js';
+export * from './types.js';
+export * from './validate.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAEH,cAAc,oBAAoB,CAAA;AAClC,cAAc,WAAW,CAAA;AACzB,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA;AAC1B,cAAc,eAAe,CAAA"}

package/dist/index.js

@@ -0,0 +1,47 @@
+/**
+ * HLS media streaming provider for molecule.dev.
+ *
+ * Provides HLS (HTTP Live Streaming) support via ffmpeg for media segmentation
+ * and transcoding, with pure-TypeScript M3U8 playlist generation. Requires
+ * ffmpeg to be installed on the host system.
+ *
+ * @example
+ * ```typescript
+ * import { setProvider, createStream } from '@molecule/api-media-streaming'
+ * import { provider } from '@molecule/api-media-streaming-hls'
+ *
+ * setProvider(provider)
+ *
+ * const manifest = await createStream('/path/to/video.mp4', {
+ *   segmentDuration: 6,
+ *   protocol: 'hls',
+ * })
+ * console.log(manifest.manifestUri) // '/hls-…/index.m3u8'
+ * ```
+ *
+ * @remarks
+ * - **Requires the `ffmpeg` binary on the host** (resolved via PATH, or set
+ *   `createProvider({ ffmpegPath })`). A missing binary fails at first
+ *   `createStream()`/`transcode()` call with `spawn ffmpeg ENOENT` — verify
+ *   with `ffmpeg -version` before shipping.
+ * - **The default output directory is `os.tmpdir()`** — volatile and served by
+ *   nothing. Pass `createProvider({ outputBasePath })` pointing at a directory
+ *   your server exposes (see the core remarks), or serve bytes through
+ *   `getSegment()` / `generateManifest()` endpoints.
+ * - `createStream()` also caches every segment `Buffer` in an in-process map
+ *   (never evicted) so `getSegment()` is fast; memory grows by the full video
+ *   size per stream. `getSegment()` disk fallback looks ONLY under
+ *   `outputBasePath/<streamId>/` — a per-call `createStream(..., { outputPath })`
+ *   override writes segments where the fallback cannot find them after a
+ *   restart, and `transcode()` ignores `outputPath` entirely (always writes
+ *   under `outputBasePath`).
+ * - `ffprobePath` in `HlsConfig` is currently RESERVED — no ffprobe call exists
+ *   yet; segment durations come from the requested `segmentDuration`.
+ *
+ * @module
+ */
+export * from './browser-guard.js';
+export * from './m3u8.js';
+export * from './provider.js';
+export * from './types.js';
+export * from './validate.js';

package/dist/m3u8.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Pure-TypeScript M3U8 (HLS playlist) generation utilities.
+ *
+ * Generates Media Playlists, Master Playlists (adaptive bitrate), and
+ * parses segment metadata — all without external dependencies.
+ *
+ * @module
+ */
+import type { StreamSegment, TranscodeVariant } from '@molecule/api-media-streaming';
+/**
+ * Options for generating an M3U8 media playlist.
+ */
+export interface M3u8PlaylistOptions {
+    /** HLS playlist version. Defaults to `3`. */
+    version?: number;
+    /** Target segment duration in seconds. Defaults to the maximum segment duration. */
+    targetDuration?: number;
+    /** Whether this is a VOD (complete) or live (in-progress) playlist. Defaults to `'vod'`. */
+    playlistType?: 'vod' | 'event';
+    /** Media sequence number for the first segment. Defaults to `0`. */
+    mediaSequence?: number;
+}
+/**
+ * Generates an M3U8 media playlist from a list of stream segments.
+ *
+ * @param segments - Ordered list of stream segments.
+ * @param options - Playlist generation options.
+ * @returns The M3U8 playlist content as a string.
+ */
+export declare const generateMediaPlaylist: (segments: StreamSegment[], options?: M3u8PlaylistOptions) => string;
+/**
+ * Generates an M3U8 master playlist for adaptive bitrate streaming.
+ *
+ * @param variants - The transcoded variant streams.
+ * @returns The master M3U8 playlist content as a string.
+ */
+export declare const generateMasterPlaylist: (variants: TranscodeVariant[]) => string;
+//# sourceMappingURL=m3u8.d.ts.map

package/dist/m3u8.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"m3u8.d.ts","sourceRoot":"","sources":["../src/m3u8.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAA;AAEpF;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,6CAA6C;IAC7C,OAAO,CAAC,EAAE,MAAM,CAAA;IAEhB,oFAAoF;IACpF,cAAc,CAAC,EAAE,MAAM,CAAA;IAEvB,4FAA4F;IAC5F,YAAY,CAAC,EAAE,KAAK,GAAG,OAAO,CAAA;IAE9B,oEAAoE;IACpE,aAAa,CAAC,EAAE,MAAM,CAAA;CACvB;AAED;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB,GAChC,UAAU,aAAa,EAAE,EACzB,UAAS,mBAAwB,KAChC,MAwBF,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,GAAI,UAAU,gBAAgB,EAAE,KAAG,MAarE,CAAA"}

package/dist/m3u8.js

@@ -0,0 +1,50 @@
+/**
+ * Pure-TypeScript M3U8 (HLS playlist) generation utilities.
+ *
+ * Generates Media Playlists, Master Playlists (adaptive bitrate), and
+ * parses segment metadata — all without external dependencies.
+ *
+ * @module
+ */
+/**
+ * Generates an M3U8 media playlist from a list of stream segments.
+ *
+ * @param segments - Ordered list of stream segments.
+ * @param options - Playlist generation options.
+ * @returns The M3U8 playlist content as a string.
+ */
+export const generateMediaPlaylist = (segments, options = {}) => {
+    const version = options.version ?? 3;
+    const targetDuration = options.targetDuration ?? Math.ceil(Math.max(...segments.map((s) => s.duration), 0));
+    const mediaSequence = options.mediaSequence ?? 0;
+    const playlistType = options.playlistType ?? 'vod';
+    const lines = [
+        '#EXTM3U',
+        `#EXT-X-VERSION:${version}`,
+        `#EXT-X-TARGETDURATION:${targetDuration}`,
+        `#EXT-X-MEDIA-SEQUENCE:${mediaSequence}`,
+        `#EXT-X-PLAYLIST-TYPE:${playlistType.toUpperCase()}`,
+    ];
+    for (const segment of segments) {
+        lines.push(`#EXTINF:${segment.duration.toFixed(6)},`);
+        lines.push(segment.uri);
+    }
+    lines.push('#EXT-X-ENDLIST');
+    lines.push('');
+    return lines.join('\n');
+};
+/**
+ * Generates an M3U8 master playlist for adaptive bitrate streaming.
+ *
+ * @param variants - The transcoded variant streams.
+ * @returns The master M3U8 playlist content as a string.
+ */
+export const generateMasterPlaylist = (variants) => {
+    const lines = ['#EXTM3U'];
+    for (const variant of variants) {
+        lines.push(`#EXT-X-STREAM-INF:BANDWIDTH=${variant.bitrate},RESOLUTION=${variant.width}x${variant.height},NAME="${variant.profile}"`);
+        lines.push(variant.uri);
+    }
+    lines.push('');
+    return lines.join('\n');
+};

package/dist/provider.d.ts

@@ -0,0 +1,23 @@
+/**
+ * HLS implementation of StreamingProvider.
+ *
+ * Uses ffmpeg (via `child_process`) for media segmentation and transcoding,
+ * and pure-TypeScript M3U8 generation for playlist creation. Requires ffmpeg
+ * to be installed on the host system.
+ *
+ * @module
+ */
+import type { StreamingProvider } from '@molecule/api-media-streaming';
+import type { HlsConfig } from './types.js';
+/**
+ * Creates an HLS streaming provider.
+ *
+ * @param config - Optional provider configuration.
+ * @returns A `StreamingProvider` backed by HLS / ffmpeg.
+ */
+export declare const createProvider: (config?: HlsConfig) => StreamingProvider;
+/**
+ * The provider implementation with default configuration.
+ */
+export declare const provider: StreamingProvider;
+//# sourceMappingURL=provider.d.ts.map

package/dist/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAQH,OAAO,KAAK,EACV,iBAAiB,EAOlB,MAAM,+BAA+B,CAAA;AAGtC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AAwD3C;;;;;GAKG;AACH,eAAO,MAAM,cAAc,GAAI,SAAQ,SAAc,KAAG,iBA8JvD,CAAA;AAED;;GAEG;AACH,eAAO,MAAM,QAAQ,EAAE,iBAAoC,CAAA"}

package/dist/provider.js

@@ -0,0 +1,202 @@
+/**
+ * HLS implementation of StreamingProvider.
+ *
+ * Uses ffmpeg (via `child_process`) for media segmentation and transcoding,
+ * and pure-TypeScript M3U8 generation for playlist creation. Requires ffmpeg
+ * to be installed on the host system.
+ *
+ * @module
+ */
+import { execFile } from 'node:child_process';
+import { mkdir, readdir, readFile, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { promisify } from 'node:util';
+import { generateMasterPlaylist, generateMediaPlaylist } from './m3u8.js';
+import { assertSafePathComponent, assertSegmentIndex, resolveWithinBase } from './validate.js';
+const execFileAsync = promisify(execFile);
+let streamCounter = 0;
+/**
+ * Generates a unique stream identifier.
+ *
+ * @returns A unique stream ID string.
+ */
+const generateStreamId = () => {
+    streamCounter += 1;
+    return `hls-${Date.now()}-${streamCounter}`;
+};
+/**
+ * Writes a Buffer input to a temporary file for ffmpeg processing.
+ *
+ * @param input - The media data.
+ * @param dir - The directory to write to.
+ * @returns The path to the written file.
+ */
+const prepareInput = async (input, dir) => {
+    if (typeof input === 'string') {
+        return input;
+    }
+    const inputPath = join(dir, 'input.tmp');
+    await writeFile(inputPath, input);
+    return inputPath;
+};
+/**
+ * Parses segment files from an output directory and builds segment metadata.
+ *
+ * @param dir - The directory containing `.ts` segment files.
+ * @param baseUri - Base URI prefix for segment URIs.
+ * @param segmentDuration - Expected segment duration in seconds.
+ * @returns An array of stream segments.
+ */
+const parseSegments = async (dir, baseUri, segmentDuration) => {
+    const files = await readdir(dir);
+    const tsFiles = files.filter((f) => f.endsWith('.ts')).sort();
+    return tsFiles.map((file, index) => ({
+        index,
+        duration: segmentDuration,
+        uri: `${baseUri}/${file}`,
+    }));
+};
+/**
+ * Creates an HLS streaming provider.
+ *
+ * @param config - Optional provider configuration.
+ * @returns A `StreamingProvider` backed by HLS / ffmpeg.
+ */
+export const createProvider = (config = {}) => {
+    const ffmpegPath = config.ffmpegPath ?? 'ffmpeg';
+    const outputBasePath = config.outputBasePath ?? tmpdir();
+    const defaultSegmentDuration = config.segmentDuration ?? 6;
+    const hlsVersion = config.hlsVersion ?? 3;
+    /** In-memory segment store keyed by `streamId:segmentIndex`. */
+    const segmentStore = new Map();
+    return {
+        async createStream(input, options) {
+            const streamId = generateStreamId();
+            const segmentDuration = options?.segmentDuration ?? defaultSegmentDuration;
+            const outputDir = join(options?.outputPath ?? outputBasePath, streamId);
+            await mkdir(outputDir, { recursive: true });
+            const inputPath = await prepareInput(input, outputDir);
+            await execFileAsync(ffmpegPath, [
+                // Restrict ffmpeg to safe protocols so a string input can't abuse dangerous
+                // ones (concat/gopher/ftp/subfile/unix) for LFI/SSRF escalation. [P5BONDS DiD]
+                '-protocol_whitelist',
+                'file,crypto,data,http,https,tcp,tls',
+                '-i',
+                inputPath,
+                '-codec',
+                'copy',
+                '-start_number',
+                '0',
+                '-hls_time',
+                String(segmentDuration),
+                '-hls_list_size',
+                '0',
+                '-hls_segment_filename',
+                join(outputDir, 'seg-%03d.ts'),
+                '-f',
+                'hls',
+                join(outputDir, 'index.m3u8'),
+            ]);
+            const segments = await parseSegments(outputDir, `/${streamId}`, segmentDuration);
+            // Store segments for later retrieval via getSegment
+            for (const segment of segments) {
+                const fileName = segment.uri.split('/').pop();
+                const data = await readFile(join(outputDir, fileName));
+                segmentStore.set(`${streamId}:${segment.index}`, data);
+            }
+            const duration = segments.reduce((sum, s) => sum + s.duration, 0);
+            return {
+                id: streamId,
+                protocol: 'hls',
+                manifestUri: `/${streamId}/index.m3u8`,
+                duration,
+                segments,
+            };
+        },
+        async transcode(input, profiles) {
+            const streamId = generateStreamId();
+            const outputDir = join(outputBasePath, streamId);
+            await mkdir(outputDir, { recursive: true });
+            const inputPath = await prepareInput(input, outputDir);
+            const variants = [];
+            for (const profile of profiles) {
+                // Reject untrusted profile names that could escape the output dir or
+                // inject ffmpeg args; the validated name is safe for fs paths + URIs.
+                assertSafePathComponent(profile.name, 'profile name');
+                const profileDir = resolveWithinBase(outputDir, profile.name);
+                await mkdir(profileDir, { recursive: true });
+                const codec = profile.codec ?? 'h264';
+                const args = [
+                    // Restrict ffmpeg to safe protocols (no concat/gopher/ftp/subfile). [P5BONDS DiD]
+                    '-protocol_whitelist',
+                    'file,crypto,data,http,https,tcp,tls',
+                    '-i',
+                    inputPath,
+                    '-c:v',
+                    codec === 'h264' ? 'libx264' : codec,
+                    '-b:v',
+                    String(profile.videoBitrate),
+                    '-c:a',
+                    'aac',
+                    '-b:a',
+                    String(profile.audioBitrate),
+                    '-vf',
+                    `scale=${profile.width}:${profile.height}`,
+                    '-start_number',
+                    '0',
+                    '-hls_time',
+                    String(defaultSegmentDuration),
+                    '-hls_list_size',
+                    '0',
+                    '-hls_segment_filename',
+                    join(profileDir, 'seg-%03d.ts'),
+                    '-f',
+                    'hls',
+                    join(profileDir, 'index.m3u8'),
+                ];
+                await execFileAsync(ffmpegPath, args);
+                variants.push({
+                    profile: profile.name,
+                    uri: `/${streamId}/${profile.name}/index.m3u8`,
+                    width: profile.width,
+                    height: profile.height,
+                    bitrate: profile.videoBitrate,
+                });
+            }
+            const masterPlaylist = generateMasterPlaylist(variants);
+            const masterPath = join(outputDir, 'master.m3u8');
+            await writeFile(masterPath, masterPlaylist, 'utf-8');
+            return {
+                id: streamId,
+                masterManifestUri: `/${streamId}/master.m3u8`,
+                variants,
+            };
+        },
+        generateManifest(segments, options) {
+            return generateMediaPlaylist(segments, {
+                version: hlsVersion,
+                targetDuration: options?.segmentDuration ?? defaultSegmentDuration,
+            });
+        },
+        async getSegment(streamId, segmentIndex) {
+            // Validate caller-supplied lookup values before any fs access — an
+            // unvalidated streamId ('../…') would escape the output base on the
+            // disk-fallback path below.
+            assertSafePathComponent(streamId, 'stream id');
+            assertSegmentIndex(segmentIndex);
+            const key = `${streamId}:${segmentIndex}`;
+            const data = segmentStore.get(key);
+            if (!data) {
+                // Fall back to reading from disk
+                const segmentPath = resolveWithinBase(outputBasePath, streamId, `seg-${String(segmentIndex).padStart(3, '0')}.ts`);
+                return readFile(segmentPath);
+            }
+            return data;
+        },
+    };
+};
+/**
+ * The provider implementation with default configuration.
+ */
+export const provider = createProvider();

package/dist/types.d.ts

@@ -0,0 +1,25 @@
+/**
+ * HLS media streaming provider configuration.
+ *
+ * @module
+ */
+/**
+ * Configuration options for the HLS streaming provider.
+ */
+export interface HlsConfig {
+    /** Path to the ffmpeg binary. Defaults to `'ffmpeg'` (resolved via PATH). */
+    ffmpegPath?: string;
+    /**
+     * Path to the ffprobe binary. RESERVED for future use — the current
+     * provider never invokes ffprobe (segment durations are taken from
+     * `segmentDuration`, not probed). Setting this has no effect today.
+     */
+    ffprobePath?: string;
+    /** Base directory where stream output files are written. Defaults to `os.tmpdir()`. */
+    outputBasePath?: string;
+    /** Default segment duration in seconds. Defaults to `6`. */
+    segmentDuration?: number;
+    /** HLS playlist version. Defaults to `3`. */
+    hlsVersion?: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,6EAA6E;IAC7E,UAAU,CAAC,EAAE,MAAM,CAAA;IAEnB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;IAEpB,uFAAuF;IACvF,cAAc,CAAC,EAAE,MAAM,CAAA;IAEvB,4DAA4D;IAC5D,eAAe,CAAC,EAAE,MAAM,CAAA;IAExB,6CAA6C;IAC7C,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB"}

package/dist/types.js

@@ -0,0 +1,6 @@
+/**
+ * HLS media streaming provider configuration.
+ *
+ * @module
+ */
+export {};

package/dist/validate.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Path-component validation helpers for the HLS provider.
+ *
+ * Caller-supplied values (stream ids, transcode profile names, segment
+ * indexes) are interpolated into filesystem paths and ffmpeg argument lists.
+ * If an application forwards untrusted input, an unvalidated component such as
+ * `../../etc` or one containing a shell metacharacter could escape the output
+ * directory or alter the ffmpeg invocation. These helpers fail closed: every
+ * such component must be a single, allow-listed path segment, and the final
+ * resolved path must stay inside its intended base directory.
+ *
+ * @module
+ */
+/**
+ * Asserts that a caller-supplied value is a safe single path component.
+ *
+ * Rejects empty strings, the relative segments `.` and `..`, anything
+ * containing a path separator or NUL byte, and anything outside the
+ * `[A-Za-z0-9._-]` allow-list (which also rejects shell metacharacters).
+ *
+ * @param value - The caller-supplied component (e.g. a stream id or profile name).
+ * @param label - Human-readable name of the field, used in the error message.
+ * @returns The validated component, unchanged.
+ * @throws {Error} If the value is not a safe single path component.
+ */
+export declare const assertSafePathComponent: (value: string, label: string) => string;
+/**
+ * Asserts that a caller-supplied segment index is a non-negative integer.
+ *
+ * @param index - The caller-supplied segment index.
+ * @returns The validated index, unchanged.
+ * @throws {Error} If the value is not a non-negative integer.
+ */
+export declare const assertSegmentIndex: (index: number) => number;
+/**
+ * Resolves `parts` against `base` and asserts the result stays within `base`.
+ *
+ * Defense-in-depth on top of {@link assertSafePathComponent}: even if a
+ * component slipped through, the resolved absolute path is rejected unless it
+ * is `base` itself or a descendant of it.
+ *
+ * @param base - The intended base directory.
+ * @param parts - Path segments to append.
+ * @returns The resolved absolute path, guaranteed to be inside `base`.
+ * @throws {Error} If the resolved path escapes `base`.
+ */
+export declare const resolveWithinBase: (base: string, ...parts: string[]) => string;
+//# sourceMappingURL=validate.d.ts.map

package/dist/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../src/validate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAYH;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,uBAAuB,GAAI,OAAO,MAAM,EAAE,OAAO,MAAM,KAAG,MActE,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,GAAI,OAAO,MAAM,KAAG,MAOlD,CAAA;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,iBAAiB,GAAI,MAAM,MAAM,EAAE,GAAG,OAAO,MAAM,EAAE,KAAG,MAOpE,CAAA"}

package/dist/validate.js

@@ -0,0 +1,77 @@
+/**
+ * Path-component validation helpers for the HLS provider.
+ *
+ * Caller-supplied values (stream ids, transcode profile names, segment
+ * indexes) are interpolated into filesystem paths and ffmpeg argument lists.
+ * If an application forwards untrusted input, an unvalidated component such as
+ * `../../etc` or one containing a shell metacharacter could escape the output
+ * directory or alter the ffmpeg invocation. These helpers fail closed: every
+ * such component must be a single, allow-listed path segment, and the final
+ * resolved path must stay inside its intended base directory.
+ *
+ * @module
+ */
+import { resolve, sep } from 'node:path';
+/**
+ * Allow-list for a single path component: ASCII alphanumerics plus `.`, `_`,
+ * and `-`. This excludes path separators (`/`, `\`), NUL, whitespace, and
+ * every shell/ffmpeg metacharacter, so a validated component is safe to use
+ * both as a filesystem segment and as an ffmpeg argument fragment.
+ */
+const SAFE_COMPONENT = /^[A-Za-z0-9._-]+$/;
+/**
+ * Asserts that a caller-supplied value is a safe single path component.
+ *
+ * Rejects empty strings, the relative segments `.` and `..`, anything
+ * containing a path separator or NUL byte, and anything outside the
+ * `[A-Za-z0-9._-]` allow-list (which also rejects shell metacharacters).
+ *
+ * @param value - The caller-supplied component (e.g. a stream id or profile name).
+ * @param label - Human-readable name of the field, used in the error message.
+ * @returns The validated component, unchanged.
+ * @throws {Error} If the value is not a safe single path component.
+ */
+export const assertSafePathComponent = (value, label) => {
+    if (typeof value !== 'string' ||
+        value.length === 0 ||
+        value === '.' ||
+        value === '..' ||
+        value.includes('\0') ||
+        !SAFE_COMPONENT.test(value)) {
+        throw new Error(`Invalid ${label}: must be a non-empty path component matching [A-Za-z0-9._-] (got ${JSON.stringify(value)})`);
+    }
+    return value;
+};
+/**
+ * Asserts that a caller-supplied segment index is a non-negative integer.
+ *
+ * @param index - The caller-supplied segment index.
+ * @returns The validated index, unchanged.
+ * @throws {Error} If the value is not a non-negative integer.
+ */
+export const assertSegmentIndex = (index) => {
+    if (typeof index !== 'number' || !Number.isInteger(index) || index < 0) {
+        throw new Error(`Invalid segment index: must be a non-negative integer (got ${JSON.stringify(index)})`);
+    }
+    return index;
+};
+/**
+ * Resolves `parts` against `base` and asserts the result stays within `base`.
+ *
+ * Defense-in-depth on top of {@link assertSafePathComponent}: even if a
+ * component slipped through, the resolved absolute path is rejected unless it
+ * is `base` itself or a descendant of it.
+ *
+ * @param base - The intended base directory.
+ * @param parts - Path segments to append.
+ * @returns The resolved absolute path, guaranteed to be inside `base`.
+ * @throws {Error} If the resolved path escapes `base`.
+ */
+export const resolveWithinBase = (base, ...parts) => {
+    const resolvedBase = resolve(base);
+    const resolved = resolve(resolvedBase, ...parts);
+    if (resolved !== resolvedBase && !resolved.startsWith(resolvedBase + sep)) {
+        throw new Error(`Resolved path escapes the output directory: ${JSON.stringify(resolved)}`);
+    }
+    return resolved;
+};

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@molecule/api-media-streaming-hls",
+  "version": "1.0.0",
+  "description": "HLS media streaming provider for molecule.dev — ffmpeg-based segmentation, transcoding, and M3U8 playlist generation",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "molecule",
+    "media",
+    "streaming",
+    "hls",
+    "m3u8",
+    "ffmpeg",
+    "transcode"
+  ],
+  "license": "Apache-2.0",
+  "peerDependencies": {
+    "@molecule/api-media-streaming": "^1.0.0"
+  },
+  "devDependencies": {
+    "@molecule/api-media-streaming": "1.0.0",
+    "@types/node": "26.1.2",
+    "typescript": "6.0.3",
+    "vitest": "4.1.10"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/molecule-dev/molecule.git",
+    "directory": "packages/api/bonds/media-streaming/hls"
+  },
+  "homepage": "https://github.com/molecule-dev/molecule/tree/main/packages/api/bonds/media-streaming/hls",
+  "bugs": "https://github.com/molecule-dev/molecule/issues",
+  "publishConfig": {
+    "access": "public"
+  }
+}