@stacksjs/video 0.70.163

package/LICENSE.md

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright (c) 2023 Open Web Foundation
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,82 @@
+# @stacksjs/video
+
+Deterministic, capability-aware video planning for Stacks. Unsupported codec operations fail early instead of being mislabeled as remuxing.
+
+## Inspect, plan, and process
+
+```ts
+import { detectVideoRuntimeCapabilities } from 'ts-videos'
+import { video } from '@stacksjs/video'
+
+const delivery = await video('uploads/demo.mp4')
+  .profile({
+    width: 1920,
+    height: 1080,
+    duration: 92,
+    frameRate: 30,
+    container: 'mp4',
+    videoCodec: 'h264',
+    audioCodec: 'aac',
+  })
+  .ladder('auto')
+  .output(['mp4', 'webm'])
+  .streaming(['hls', 'dash'])
+  .runtime(await detectVideoRuntimeCapabilities())
+  .process({ signal: request.signal })
+```
+
+`.generate()` returns the deterministic plan without processing. `.process()` executes its container and rendition matrix through native WebCodecs and the built-in MP4 or WebM muxers. The same call returns progressive files, CMAF segments, HLS and DASH manifests, poster art, preview sprites, and preview WebVTT when the native preview runtime is available. Compatible packets are copied, real codec changes are encoded, scaling never upscales, metadata is preserved, and work runs in bounded batches.
+
+```ts
+await storage.putMany(delivery.files)
+```
+
+## HLS, DASH, and protected delivery
+
+```ts
+import { createAdaptiveDeliveryBundle } from 'ts-videos/protected-delivery'
+
+const bundle = await createAdaptiveDeliveryBundle(plan, segmentedRenditions, {
+  hlsAes128: {
+    key,
+    keyUri: '/media/keys/demo',
+  },
+  drm: {
+    descriptors: [{ system: 'widevine', keyId, licenseUrl }],
+    dashSegmentsEncrypted: true,
+  },
+})
+```
+
+HLS AES-128 is performed with Web Crypto. Widevine, PlayReady, FairPlay, and ClearKey descriptors require already encrypted CENC or SAMPLE-AES media. Clear segments cannot be labeled as proprietary DRM content.
+
+For hosted delivery, publish immutable segments to S3 and use the media helpers from `ts-cloud`:
+
+```ts
+import { buildMediaCdnPlan, signCloudFrontCookies } from 'ts-cloud'
+
+const cdn = buildMediaCdnPlan({
+  bucket: 'example-media',
+  region: 'us-west-2',
+  domain: 'media.example.com',
+  protected: true,
+})
+const cookies = signCloudFrontCookies({ resource: 'https://media.example.com/demo/*', expires }, signer)
+```
+
+Manifests remain short-lived or private, while content-addressed segments use immutable caching. Key routes must enforce the same application authorization or signed audience boundary.
+
+## Default STX player
+
+```stx
+<Video
+  src="/media/demo/manifest.mpd"
+  title="Product demonstration"
+  poster="/media/demo/poster.avif"
+  :sources="progressiveFallbacks"
+  :tracks="captionAndChapterTracks"
+  :drm="drm"
+/>
+```
+
+The default UI includes play, seek, live edge, time, mute, volume, speed, quality, captions, audio tracks, AirPlay, Remote Playback, Picture in Picture, fullscreen, and accessible errors. Native video controls remain as the no-JavaScript fallback.

package/dist/index.d.ts

@@ -0,0 +1,36 @@
+export declare function deriveVideoLadder(profile: VideoProfile, maximum?: number): VideoRendition[];
+export declare function video(source: string): VideoBuilder;
+export declare function processVideoPlan(plan: VideoPlan, options?: VideoProcessOptions): Promise<ProcessedVideoDelivery>;
+export declare function assertVideoPlanExecutable(plan: VideoPlan): void;
+export declare function createHlsMaster(plan: VideoPlan, uri: (rendition: VideoRendition) => string): string;
+export declare function createPreviewVtt(cues: readonly PreviewCue[]): string;
+export declare function videoResponseHeaders(bytes: number, etag: string, contentType: string): Record<string, string>;
+export declare function signVideoAsset(path: string, expires: number, secret: string): string;
+export declare function verifyVideoAsset(path: string, expires: number, signature: string, secret: string, now?: number): boolean;
+export declare function createProtectedVideoPlaylist(segments: VideoSegment[], protection?: VideoHlsProtection): Promise<ProtectedVideoPlaylist>;
+export declare function videoAssetHeaders(path: string, bytes?: number, etag?: string, protectedMedia?: boolean): Record<string, string>;
+export declare interface VideoProfile { width: number, height: number, duration: number, frameRate: number, container: VideoContainer, videoCodec: VideoCodec, audioCodec?: VideoAudioCodec, videoBitrate?: number, hasAudio?: boolean, hdr?: boolean }
+export declare interface VideoRendition { name: string, width: number, height: number, frameRate: number, videoBitrate: number, audioBitrate: number }
+export declare interface VideoCapabilities { videoEncoder: boolean, audioEncoder: boolean, videoCodecs: string[], audioCodecs: string[] }
+export declare interface VideoOutput { container: VideoContainer, videoCodec: VideoCodec, audioCodec?: VideoAudioCodec, action: 'copy' | 'transcode', available: boolean, reason?: string }
+export declare interface VideoPlan { source: string, profile: VideoProfile, renditions: VideoRendition[], outputs: VideoOutput[], streaming: StreamingFormat[], segmentDuration: number, keyframeInterval: number }
+export declare interface PreviewCue { startTime: number, endTime: number, uri: string, x?: number, y?: number, width?: number, height?: number }
+export declare interface VideoSegment { uri: string, duration: number, data: Uint8Array }
+export declare interface VideoHlsProtection { key: Uint8Array, keyUri: string, iv?: (_index: number) => Uint8Array }
+export declare interface ProtectedVideoPlaylist { playlist: string, files: Record<string, Uint8Array>, encrypted: boolean }
+export type VideoContainer = 'mp4' | 'webm';
+export type StreamingFormat = 'hls' | 'dash';
+export type VideoCodec = 'h264' | 'h265' | 'vp8' | 'vp9' | 'av1' | 'mpeg1' | 'mpeg2' | 'mpeg4' | 'theora' | 'mjpeg' | 'prores' | 'dnxhd' | 'unknown';
+export type VideoAudioCodec = 'aac' | 'mp3' | 'opus' | 'vorbis' | 'flac' | 'alac' | 'ac3' | 'eac3' | 'dts' | 'pcm_s16le' | 'pcm_s16be' | 'pcm_s24le' | 'pcm_s24be' | 'pcm_s32le' | 'pcm_s32be' | 'pcm_f32le' | 'pcm_f32be' | 'pcm_f64le' | 'pcm_f64be' | 'pcm_mulaw' | 'pcm_alaw' | 'unknown';
+export type VideoProcessOptions = import('ts-videos/delivery-pipeline').VideoDeliveryPipelineOptions;
+export type ProcessedVideoDelivery = import('ts-videos/delivery-pipeline').VideoDeliveryPipelineResult;
+export declare class VideoBuilder {
+  constructor(source: string);
+  profile(value: VideoProfile): this;
+  ladder(value: 'auto' | number): this;
+  output(formats: VideoContainer[]): this;
+  streaming(formats: StreamingFormat[]): this;
+  runtime(value: VideoCapabilities): this;
+  generate(): VideoPlan;
+  process(options?: VideoProcessOptions): Promise<ProcessedVideoDelivery>;
+}

package/dist/index.js

@@ -0,0 +1,170 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+const edges = [240, 360, 480, 540, 720, 1080, 1440, 2160], even = (value) => Math.max(2, Math.round(value / 2) * 2);
+function validate(profile) {
+  for (const [name, value] of Object.entries({ width: profile.width, height: profile.height, duration: profile.duration, frameRate: profile.frameRate }))
+    if (!Number.isFinite(value) || value <= 0)
+      throw TypeError(`Video ${name} must be positive`);
+}
+export function deriveVideoLadder(profile, maximum) {
+  validate(profile);
+  const short = Math.min(profile.width, profile.height), limit = Math.min(short, maximum ?? short), targets = edges.filter((edge) => edge <= limit);
+  if (!targets.includes(limit))
+    targets.push(limit);
+  return [...new Set(targets)].sort((a, b) => a - b).map((edge) => {
+    const scale = edge / short, width = even(profile.width * scale), height = even(profile.height * scale), rate = Math.round(width * height * Math.min(60, profile.frameRate) * 0.075 * (profile.frameRate > 30 ? Math.min(2, profile.frameRate / 30) : 1) * (profile.hdr ? 1.25 : 1) / 1000) * 1000;
+    return { name: `${edge}p`, width, height, frameRate: profile.frameRate, videoBitrate: Math.max(250000, Math.min(profile.videoBitrate ?? 1 / 0, rate)), audioBitrate: profile.hasAudio === !1 ? 0 : width >= 1280 ? 192000 : 128000 };
+  }).filter((item, index, all) => item.width <= profile.width && item.height <= profile.height && all.findIndex((value) => value.width === item.width && value.height === item.height) === index);
+}
+
+export class VideoBuilder {
+  source;
+  inspected;
+  formats = ["mp4", "webm"];
+  streams = ["hls", "dash"];
+  maximum;
+  capabilities = { videoEncoder: !1, audioEncoder: !1, videoCodecs: [], audioCodecs: [] };
+  constructor(source) {
+    this.source = source;
+  }
+  profile(value) {
+    validate(value);
+    this.inspected = value;
+    return this;
+  }
+  ladder(value) {
+    if (value !== "auto" && (!Number.isInteger(value) || value <= 0))
+      throw TypeError("Video ladder height must be positive");
+    this.maximum = value === "auto" ? void 0 : value;
+    return this;
+  }
+  output(formats) {
+    if (!formats.length)
+      throw TypeError("Video formats are required");
+    this.formats = [...new Set(formats)];
+    return this;
+  }
+  streaming(formats) {
+    this.streams = [...new Set(formats)];
+    return this;
+  }
+  runtime(value) {
+    this.capabilities = value;
+    return this;
+  }
+  generate() {
+    if (!this.inspected)
+      throw Error("Video inspection is required; pass its profile with .profile()");
+    const profile = this.inspected, renditions = deriveVideoLadder(profile, this.maximum), outputs = this.formats.map((container) => {
+      const videoCodec = container === "mp4" ? "h264" : "vp9", audioCodec = profile.hasAudio === !1 ? void 0 : container === "mp4" ? "aac" : "opus", copy = renditions.length === 1 && renditions[0].width === profile.width && renditions[0].height === profile.height && profile.container === container && profile.videoCodec === videoCodec && (!audioCodec || profile.audioCodec === audioCodec), available = copy || this.capabilities.videoEncoder && this.capabilities.videoCodecs.includes(videoCodec) && (!audioCodec || this.capabilities.audioEncoder && this.capabilities.audioCodecs.includes(audioCodec));
+      return { container, videoCodec, audioCodec, action: copy ? "copy" : "transcode", available, reason: available ? void 0 : `Native ${videoCodec}${audioCodec ? `/${audioCodec}` : ""} encoding is unavailable` };
+    }), segmentDuration = profile.duration <= 30 ? 2 : profile.duration <= 600 ? 4 : 6;
+    return { source: this.source, profile, renditions, outputs, streaming: this.streams, segmentDuration, keyframeInterval: Math.max(1, Math.round(profile.frameRate * segmentDuration)) };
+  }
+  async process(options = {}) {
+    return processVideoPlan(this.generate(), options);
+  }
+}
+export function video(source) {
+  return new VideoBuilder(source);
+}
+export async function processVideoPlan(plan, options = {}) {
+  assertVideoPlanExecutable(plan);
+  const { createVideoDeliveryPipeline } = await import("ts-videos/delivery-pipeline");
+  return createVideoDeliveryPipeline(plan.source, {
+    source: plan.profile,
+    renditions: plan.renditions,
+    outputs: plan.outputs,
+    streaming: plan.streaming,
+    segmentDuration: plan.segmentDuration,
+    keyframeInterval: plan.keyframeInterval
+  }, options);
+}
+export function assertVideoPlanExecutable(plan) {
+  const missing = plan.outputs.filter((value) => !value.available);
+  if (missing.length)
+    throw Error(missing.map((value) => `${value.container}: ${value.reason}`).join("; "));
+}
+export function createHlsMaster(plan, uri) {
+  const lines = ["#EXTM3U", "#EXT-X-VERSION:7", "#EXT-X-INDEPENDENT-SEGMENTS"], output = plan.outputs.find((value) => value.container === "mp4");
+  for (const item of plan.renditions) {
+    lines.push(`#EXT-X-STREAM-INF:BANDWIDTH=${item.videoBitrate + item.audioBitrate},AVERAGE-BANDWIDTH=${Math.round((item.videoBitrate + item.audioBitrate) * 0.9)},RESOLUTION=${item.width}x${item.height},FRAME-RATE=${item.frameRate.toFixed(3)},CODECS="${output?.videoCodec ?? plan.profile.videoCodec}${output?.audioCodec ? `,${output.audioCodec}` : ""}"`);
+    lines.push(uri(item));
+  }
+  return `${lines.join(`
+`)}
+`;
+}
+function time(seconds) {
+  const ms = Math.round(seconds * 1000);
+  return `${String(Math.floor(ms / 3600000)).padStart(2, "0")}:${String(Math.floor(ms % 3600000 / 60000)).padStart(2, "0")}:${String(Math.floor(ms % 60000 / 1000)).padStart(2, "0")}.${String(ms % 1000).padStart(3, "0")}`;
+}
+export function createPreviewVtt(cues) {
+  let end = 0;
+  const lines = ["WEBVTT", ""];
+  cues.forEach((cue, index) => {
+    if (cue.startTime < end || cue.endTime <= cue.startTime)
+      throw TypeError(`Invalid preview cue ${index}`);
+    const sprite = [cue.x, cue.y, cue.width, cue.height].every((value) => value !== void 0);
+    lines.push(`${time(cue.startTime)} --> ${time(cue.endTime)}`, sprite ? `${cue.uri}#xywh=${cue.x},${cue.y},${cue.width},${cue.height}` : cue.uri, "");
+    end = cue.endTime;
+  });
+  return lines.join(`
+`);
+}
+export function videoResponseHeaders(bytes, etag, contentType) {
+  return { "Accept-Ranges": "bytes", "Content-Length": String(bytes), "Content-Type": contentType, "Cache-Control": "public, max-age=31536000, immutable", ETag: `"${etag}"` };
+}
+export function signVideoAsset(path, expires, secret) {
+  return createHmac("sha256", secret).update(`${path}
+${expires}`).digest("base64url");
+}
+export function verifyVideoAsset(path, expires, signature, secret, now = Date.now()) {
+  if (!Number.isInteger(expires) || expires * 1000 <= now)
+    return !1;
+  const expected = Buffer.from(signVideoAsset(path, expires, secret)), actual = Buffer.from(signature);
+  return expected.length === actual.length && timingSafeEqual(expected, actual);
+}
+function sequenceIv(index) {
+  const value = new Uint8Array(16);
+  new DataView(value.buffer).setBigUint64(8, BigInt(index));
+  return value;
+}
+function hex(value) {
+  return [...value].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+async function encryptAes(data, key, iv) {
+  if (key.byteLength !== 16 || iv.byteLength !== 16)
+    throw TypeError("HLS AES-128 keys and IVs must contain 16 bytes");
+  const keyBytes = Uint8Array.from(key), ivBytes = Uint8Array.from(iv), dataBytes = Uint8Array.from(data), cryptoKey = await crypto.subtle.importKey("raw", keyBytes.buffer, { name: "AES-CBC" }, !1, ["encrypt"]);
+  return new Uint8Array(await crypto.subtle.encrypt({ name: "AES-CBC", iv: ivBytes.buffer }, cryptoKey, dataBytes.buffer));
+}
+export async function createProtectedVideoPlaylist(segments, protection) {
+  if (!segments.length)
+    throw TypeError("Video playlist requires segments");
+  if (protection && /[\r\n"]/.test(protection.keyUri))
+    throw TypeError("Invalid video key URI");
+  const lines = ["#EXTM3U", "#EXT-X-VERSION:7", `#EXT-X-TARGETDURATION:${Math.ceil(Math.max(...segments.map((item) => item.duration)))}`, "#EXT-X-PLAYLIST-TYPE:VOD", "#EXT-X-INDEPENDENT-SEGMENTS"], files = {};
+  for (const [index, segment] of segments.entries()) {
+    if (!Number.isFinite(segment.duration) || segment.duration <= 0 || /[\r\n"]/.test(segment.uri))
+      throw TypeError(`Invalid video segment ${index}`);
+    let data = segment.data;
+    if (protection) {
+      const iv = protection.iv?.(index) ?? sequenceIv(index);
+      data = await encryptAes(data, protection.key, iv);
+      lines.push(`#EXT-X-KEY:METHOD=AES-128,URI="${protection.keyUri}",IV=0x${hex(iv)}`);
+    }
+    lines.push(`#EXTINF:${segment.duration.toFixed(6)},`, segment.uri);
+    files[segment.uri] = data;
+  }
+  lines.push("#EXT-X-ENDLIST", "");
+  return { playlist: lines.join(`
+`), files, encrypted: !!protection };
+}
+export function videoAssetHeaders(path, bytes, etag, protectedMedia = !1) {
+  const manifest = /\.(?:m3u8|mpd|vtt)$/i.test(path), headers = { "Accept-Ranges": "bytes", "Cache-Control": protectedMedia && manifest ? "private, no-store" : manifest ? "public, max-age=5, s-maxage=30" : "public, max-age=31536000, immutable", "X-Content-Type-Options": "nosniff" };
+  if (bytes !== void 0)
+    headers["Content-Length"] = String(bytes);
+  if (etag)
+    headers.ETag = `"${etag}"`;
+  return headers;
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@stacksjs/video",
+  "type": "module",
+  "sideEffects": false,
+  "version": "0.70.163",
+  "description": "Native video delivery planning for Stacks.",
+  "author": "Chris Breuer",
+  "license": "MIT",
+  "funding": "https://github.com/sponsors/chrisbbreuer",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/stacksjs/stacks.git",
+    "directory": "./storage/framework/core/video"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "development": "./src/index.ts",
+      "bun": "./dist/index.js",
+      "import": "./dist/index.js"
+    }
+  },
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "README.md",
+    "dist"
+  ],
+  "scripts": {
+    "build": "bun build.ts",
+    "typecheck": "bun tsc --noEmit",
+    "prepublishOnly": "bun run build"
+  },
+  "dependencies": {
+    "ts-video-player": "^0.1.0",
+    "ts-videos": "^0.1.1"
+  },
+  "devDependencies": {
+    "better-dx": "^0.2.17"
+  }
+}