@stacksjs/audio 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,66 @@
+# @stacksjs/audio
+
+Capability-aware audio planning, format negotiation, waveforms, and transcript normalization for Stacks.
+
+## Process music, podcasts, and voice
+
+```ts
+import { detectAudioRuntimeCapabilities } from '@ts-audio/core'
+import { audio } from '@stacksjs/audio'
+
+const derivatives = await audio('uploads/episode.flac')
+  .profile({
+    codec: 'flac',
+    container: 'flac',
+    duration: 1842,
+    sampleRate: 48_000,
+    channels: 2,
+  })
+  .content('speech')
+  .output(['opus', 'aac', 'mp3'])
+  .loudness(-16)
+  .runtime(await detectAudioRuntimeCapabilities())
+  .process({ signal: request.signal })
+```
+
+Use `.content('music')` for music bitrate guidance, `.content('speech')` for podcasts and voice, or `.content('general')` for mixed material. AAC output uses a native ADTS `.aac` container, Opus uses Ogg, and MP3 uses its native container. `.generate()` can inspect the plan without processing it.
+
+## Negotiation, waveform, and transcripts
+
+```ts
+import { createWaveform, negotiateAudioOutput, normalizeTranscript } from '@stacksjs/audio'
+
+const selected = negotiateAudioOutput(plan.outputs, request.headers.get('accept') ?? '*/*')
+const waveform = createWaveform(decodedChannels, sampleRate, 1200)
+const transcript = normalizeTranscript('en', providerSegments)
+```
+
+Transcription remains provider-neutral. Call the provider explicitly, bind its cache key to the source hash, language, provider version, and options, then store the normalized WebVTT beside the private media.
+
+## HLS, private CDN, and DRM
+
+```ts
+import { createProtectedAudioPlaylist } from '@stacksjs/audio'
+
+const delivery = await createProtectedAudioPlaylist(segments, {
+  key,
+  keyUri: '/media/keys/episode',
+})
+```
+
+Native HLS AES-128 uses Web Crypto. Proprietary DRM metadata is accepted only for already encrypted media. Publish immutable audio segments to S3 and protect manifests, keys, waveform data, transcripts, and metadata with the same CloudFront signed URL, signed cookie, or application authorization boundary.
+
+## Default STX player
+
+```stx
+<Audio
+  src="/media/episode/index.m3u8"
+  title="Episode 12"
+  artist="Stacks"
+  waveform="/media/episode/waveform.svg"
+  :sources="progressiveFallbacks"
+  :tracks="chapterAndTranscriptTracks"
+/>
+```
+
+The default UI includes play, seek, time, mute, volume, speed, settings, waveform seeking, AirPlay, and Remote Playback. Native audio controls remain available before custom elements load and when JavaScript is unavailable.

package/dist/index.d.ts

@@ -0,0 +1,35 @@
+export declare function recommendAudioBitrate(format: AudioFormat, source: AudioProfile, content: AudioContent): number;
+export declare function audio(source: string): AudioBuilder;
+export declare function processAudioPlan(plan: AudioPlan, options?: AudioProcessOptions): Promise<ProcessedAudioDerivative[]>;
+export declare function assertAudioPlanExecutable(plan: AudioPlan): void;
+export declare function negotiateAudioOutput(outputs: readonly AudioOutput[], accept?: string): AudioOutput | undefined;
+export declare function createWaveform(channels: readonly Float32Array[], sampleRate: number, samples?: number, precision?: number): Waveform;
+export declare function normalizeTranscript(language: string, input: readonly TranscriptSegment[]): Transcript;
+export declare function audioResponseHeaders(bytes: number, etag: string, contentType: string): Record<string, string>;
+export declare function signAudioAsset(path: string, expires: number, secret: string): string;
+export declare function verifyAudioAsset(path: string, expires: number, signature: string, secret: string, now?: number): boolean;
+export declare function createProtectedAudioPlaylist(segments: AudioSegment[], protection?: AudioHlsProtection): Promise<{ playlist: string, files: Record<string, Uint8Array>, encrypted: boolean }>;
+export declare interface AudioProfile { codec: AudioCodec, container: string, duration: number, sampleRate: number, channels: number, bitrate?: number }
+export declare interface AudioCapabilities { encoder: boolean, codecs: AudioFormat[] }
+export declare interface AudioOutput { format: AudioFormat, container: 'ogg' | 'aac' | 'mp3', mimeType: 'audio/ogg; codecs=opus' | 'audio/aac' | 'audio/mpeg', extension: 'ogg' | 'aac' | 'mp3', bitrate: number, action: 'copy' | 'transcode', available: boolean, reason?: string }
+export declare interface AudioPlan { source: string, profile: AudioProfile, outputs: AudioOutput[], loudness: number }
+export declare interface AudioProcessOptions { batchSize?: number, signal?: AbortSignal }
+export declare interface ProcessedAudioDerivative { output: AudioOutput, bytes: Uint8Array }
+export declare interface Waveform { version: 1, channels: number, sampleRate: number, duration: number, samplesPerPeak: number, peaks: number[][] }
+export declare interface TranscriptSegment { startTime: number, endTime: number, text: string, confidence?: number, speaker?: string }
+export declare interface Transcript { language: string, segments: Array<TranscriptSegment & { id: number }>, vtt: string }
+export declare interface AudioSegment { uri: string, duration: number, data: Uint8Array }
+export declare interface AudioHlsProtection { key: Uint8Array, keyUri: string }
+export type AudioFormat = 'opus' | 'aac' | 'mp3';
+export type AudioContent = 'speech' | 'music' | 'general';
+export type AudioCodec = 'aac' | 'mp3' | 'opus' | 'vorbis' | 'flac' | 'alac' | 'pcm_s16le' | 'pcm_s24le' | 'pcm_s32le' | 'pcm_f32le' | 'pcm_f64le';
+export declare class AudioBuilder {
+  constructor(source: string);
+  profile(value: AudioProfile): this;
+  output(value: AudioFormat[]): this;
+  content(value: AudioContent): this;
+  loudness(value: number): this;
+  runtime(value: AudioCapabilities): this;
+  generate(): AudioPlan;
+  process(options?: AudioProcessOptions): Promise<ProcessedAudioDerivative[]>;
+}

package/dist/index.js

@@ -0,0 +1,173 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+const details = { opus: { container: "ogg", mimeType: "audio/ogg; codecs=opus", extension: "ogg" }, aac: { container: "aac", mimeType: "audio/aac", extension: "aac" }, mp3: { container: "mp3", mimeType: "audio/mpeg", extension: "mp3" } };
+function validate(profile) {
+  for (const [name, value] of Object.entries({ duration: profile.duration, sampleRate: profile.sampleRate, channels: profile.channels }))
+    if (!Number.isFinite(value) || value <= 0)
+      throw TypeError(`Audio ${name} must be positive`);
+}
+export function recommendAudioBitrate(format, source, content) {
+  const channels = Math.min(2, Math.max(1, source.channels)), rate = source.sampleRate <= 24000 ? 0.75 : source.sampleRate >= 88200 ? 1.15 : 1, base = content === "speech" ? channels === 1 ? 48000 : 64000 : content === "music" ? channels === 1 ? 96000 : 192000 : channels === 1 ? 64000 : 128000;
+  return Math.max(32000, Math.min(source.bitrate ?? 1 / 0, Math.round(base * rate * (format === "opus" ? 0.8 : format === "mp3" ? 1.2 : 1) / 1000) * 1000));
+}
+
+export class AudioBuilder {
+  source;
+  inspected;
+  formats = ["opus", "aac", "mp3"];
+  contentType = "general";
+  targetLoudness = -16;
+  capabilities = { encoder: !1, codecs: [] };
+  constructor(source) {
+    this.source = source;
+  }
+  profile(value) {
+    validate(value);
+    this.inspected = value;
+    return this;
+  }
+  output(value) {
+    if (!value.length)
+      throw TypeError("Audio formats are required");
+    this.formats = [...new Set(value)];
+    return this;
+  }
+  content(value) {
+    this.contentType = value;
+    return this;
+  }
+  loudness(value) {
+    if (!Number.isFinite(value) || value < -70 || value > 0)
+      throw TypeError("Audio loudness must be between -70 and 0 LUFS");
+    this.targetLoudness = value;
+    return this;
+  }
+  runtime(value) {
+    this.capabilities = value;
+    return this;
+  }
+  generate() {
+    if (!this.inspected)
+      throw Error("Audio inspection is required; pass its profile with .profile()");
+    const profile = this.inspected, outputs = this.formats.map((format) => {
+      const info = details[format], copy = profile.codec === format && (profile.container === info.container || profile.container === info.extension), available = copy || this.capabilities.encoder && this.capabilities.codecs.includes(format);
+      return { format, ...info, bitrate: recommendAudioBitrate(format, profile, this.contentType), action: copy ? "copy" : "transcode", available, reason: available ? void 0 : `Native ${format} encoding is unavailable` };
+    });
+    return { source: this.source, profile, outputs, loudness: this.targetLoudness };
+  }
+  async process(options = {}) {
+    return processAudioPlan(this.generate(), options);
+  }
+}
+export function audio(source) {
+  return new AudioBuilder(source);
+}
+export async function processAudioPlan(plan, options = {}) {
+  assertAudioPlanExecutable(plan);
+  const { generateAudioDerivatives } = await import("@ts-audio/core/native-transcode");
+  return generateAudioDerivatives(plan.source, { source: plan.profile, outputs: plan.outputs }, options);
+}
+export function assertAudioPlanExecutable(plan) {
+  const missing = plan.outputs.filter((value) => !value.available);
+  if (missing.length)
+    throw Error(missing.map((value) => `${value.format}: ${value.reason}`).join("; "));
+}
+function q(accept, mime) {
+  const [type = "", subtype = ""] = (mime.split(";", 1)[0] ?? "").split("/");
+  let best = 0;
+  for (const item of accept.split(",")) {
+    const [range = "*/*", ...params] = item.trim().toLowerCase().split(";").map((value) => value.trim()), [a = "*", b = "*"] = range.split("/");
+    if ((a === "*" || a === type) && (b === "*" || b === subtype)) {
+      const raw = params.find((value) => value.startsWith("q="));
+      best = Math.max(best, raw ? Number.parseFloat(raw.slice(2)) || 0 : 1);
+    }
+  }
+  return best;
+}
+export function negotiateAudioOutput(outputs, accept = "*/*") {
+  return outputs.filter((value) => value.available).map((output, index) => ({ output, index, q: q(accept || "*/*", output.mimeType) })).filter((value) => value.q > 0).sort((a, b) => b.q - a.q || a.index - b.index)[0]?.output;
+}
+export function createWaveform(channels, sampleRate, samples = 1000, precision = 4) {
+  if (!channels.length || sampleRate <= 0)
+    throw TypeError("Waveform requires channels and a positive sample rate");
+  const frames = channels[0].length;
+  if (channels.some((channel) => channel.length !== frames))
+    throw TypeError("Waveform channels must have equal lengths");
+  const size = Math.max(1, Math.ceil(frames / Math.max(1, Math.min(frames || 1, Math.floor(samples)))));
+  let absolute = 0;
+  const raw = channels.map((channel) => {
+    const peaks = [];
+    for (let start = 0;start < frames; start += size) {
+      let min = 1, max = -1;
+      for (let index = start;index < Math.min(frames, start + size); index++) {
+        const sample = channel[index] ?? 0, value = Number.isFinite(sample) ? Math.max(-1, Math.min(1, sample)) : 0;
+        min = Math.min(min, value);
+        max = Math.max(max, value);
+        absolute = Math.max(absolute, Math.abs(value));
+      }
+      peaks.push([min, max]);
+    }
+    return peaks;
+  }), divisor = absolute || 1, round = (value) => Number((value / divisor).toFixed(Math.max(0, Math.min(6, precision))));
+  return { version: 1, channels: channels.length, sampleRate, duration: frames / sampleRate, samplesPerPeak: size, peaks: raw.map((channel) => channel.flatMap(([min, max]) => [round(min), round(max)])) };
+}
+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 normalizeTranscript(language, input) {
+  if (!language.trim())
+    throw TypeError("Transcript language is required");
+  let end = 0;
+  const segments = input.map((item, index) => {
+    if (item.startTime < end || item.startTime < 0 || item.endTime <= item.startTime || !item.text.trim())
+      throw TypeError(`Invalid transcript segment ${index}`);
+    if (item.confidence !== void 0 && (item.confidence < 0 || item.confidence > 1))
+      throw TypeError(`Invalid transcript confidence ${index}`);
+    end = item.endTime;
+    return { ...item, text: item.text.trim(), id: index + 1 };
+  }), lines = ["WEBVTT", ""];
+  for (const item of segments)
+    lines.push(String(item.id), `${time(item.startTime)} --> ${time(item.endTime)}`, item.speaker ? `<v ${item.speaker}>${item.text}` : item.text, "");
+  return { language: language.trim().toLowerCase(), segments, vtt: lines.join(`
+`) };
+}
+export function audioResponseHeaders(bytes, etag, contentType) {
+  return { "Accept-Ranges": "bytes", "Content-Length": String(bytes), "Content-Type": contentType, "Cache-Control": "public, max-age=31536000, immutable", ETag: `"${etag}"`, Vary: "Accept" };
+}
+export function signAudioAsset(path, expires, secret) {
+  return createHmac("sha256", secret).update(`${path}
+${expires}`).digest("base64url");
+}
+export function verifyAudioAsset(path, expires, signature, secret, now = Date.now()) {
+  if (!Number.isInteger(expires) || expires * 1000 <= now)
+    return !1;
+  const expected = Buffer.from(signAudioAsset(path, expires, secret)), actual = Buffer.from(signature);
+  return expected.length === actual.length && timingSafeEqual(expected, actual);
+}
+export async function createProtectedAudioPlaylist(segments, protection) {
+  if (!segments.length)
+    throw TypeError("Audio playlist requires segments");
+  if (protection && /[\r\n"]/.test(protection.keyUri))
+    throw TypeError("Invalid audio key URI");
+  const files = {}, lines = ["#EXTM3U", "#EXT-X-VERSION:7", `#EXT-X-TARGETDURATION:${Math.ceil(Math.max(...segments.map((item) => item.duration)))}`, "#EXT-X-PLAYLIST-TYPE:VOD"];
+  for (const [index, segment] of segments.entries()) {
+    if (!Number.isFinite(segment.duration) || segment.duration <= 0 || /[\r\n"]/.test(segment.uri))
+      throw TypeError(`Invalid audio segment ${index}`);
+    let data = segment.data;
+    if (protection) {
+      if (protection.key.byteLength !== 16)
+        throw TypeError("Audio HLS AES-128 key must contain 16 bytes");
+      const iv = new Uint8Array(16);
+      new DataView(iv.buffer).setBigUint64(8, BigInt(index));
+      const key = Uint8Array.from(protection.key), input = Uint8Array.from(data), cryptoKey = await crypto.subtle.importKey("raw", key.buffer, { name: "AES-CBC" }, !1, ["encrypt"]);
+      data = new Uint8Array(await crypto.subtle.encrypt({ name: "AES-CBC", iv: iv.buffer }, cryptoKey, input.buffer));
+      const ivHex = [...iv].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+      lines.push(`#EXT-X-KEY:METHOD=AES-128,URI="${protection.keyUri}",IV=0x${ivHex}`);
+    }
+    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 };
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@stacksjs/audio",
+  "type": "module",
+  "sideEffects": false,
+  "version": "0.70.163",
+  "description": "Native audio 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/audio"
+  },
+  "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-audio/core": "^0.1.1",
+    "ts-video-player": "^0.1.0"
+  },
+  "devDependencies": {
+    "better-dx": "^0.2.17"
+  }
+}