omni-viewer-core 0.1.0

package/dist/viewers/audio/controller.js

@@ -0,0 +1,49 @@
+// DOM-free presentation state for the waveform audio viewer. Playback time
+// and play/pause live on the WaveSurfer instance (the engine owns them); the
+// controller holds the pure knobs the toolbar mutates.
+export const AUDIO_MIN_ZOOM = 1;
+export const AUDIO_MAX_ZOOM = 32;
+export const AUDIO_VOLUME_STEPS = 100;
+const clampZoom = (zoom) => Math.min(AUDIO_MAX_ZOOM, Math.max(AUDIO_MIN_ZOOM, zoom));
+export function createAudioController() {
+    let zoom = 1;
+    let volume = 1;
+    let loop = false;
+    let visualization = 'waveform';
+    const listeners = new Set();
+    const snapshot = () => ({ zoom, volume, loop, visualization });
+    const emit = () => listeners.forEach((listener) => listener(snapshot()));
+    return {
+        get state() { return snapshot(); },
+        dispatch(action) {
+            const before = snapshot();
+            switch (action.type) {
+                case 'zoom-in':
+                    zoom = clampZoom(zoom * 2);
+                    break;
+                case 'zoom-out':
+                    zoom = clampZoom(zoom / 2);
+                    break;
+                case 'zoom-fit':
+                    zoom = 1;
+                    break;
+                case 'set-volume':
+                    volume = Math.min(1, Math.max(0, action.volume));
+                    break;
+                case 'toggle-loop':
+                    loop = !loop;
+                    break;
+                case 'set-visualization':
+                    visualization = action.visualization;
+                    break;
+            }
+            const after = snapshot();
+            if (JSON.stringify(before) !== JSON.stringify(after))
+                emit();
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        }
+    };
+}

package/dist/viewers/audio/engine.d.ts

@@ -0,0 +1,44 @@
+import type { HostContext } from '../../host/index.js';
+export interface DecodedAudio {
+    sampleRate: number;
+    channels: number;
+    frames: number;
+    /** Interleaved float32 samples, length === frames * channels. */
+    pcm: Float32Array;
+}
+export interface AudioAnalysis {
+    sampleRate: number;
+    channels: number;
+    duration: number;
+    /** Mono peak per pixel column, 0..1. */
+    peaks: number[];
+}
+export interface AudioDecodeEngine {
+    decode(data: Uint8Array): Promise<DecodedAudio>;
+    analyze(data: Uint8Array, width: number): Promise<AudioAnalysis>;
+}
+/** Emscripten module surface used by the bridge (see native/audio-engine). */
+export interface AudioEngineModuleLike {
+    HEAPU8: Uint8Array;
+    HEAPF32: Float32Array;
+    getValue(pointer: number, type: string): number;
+    _malloc(size: number): number;
+    _free(pointer: number): void;
+    _decode_audio(pointer: number, length: number): number;
+    _audio_get_channels(audio: number): number;
+    _audio_get_sample_rate(audio: number): number;
+    _audio_get_total_frames(audio: number): number;
+    _audio_get_total_frames_high(audio: number): number;
+    _generate_peaks(audio: number, width: number): number;
+    _free_audio(audio: number): void;
+    _free_buffer(pointer: number): void;
+}
+export declare function createWasmAudioEngine(loadModule: () => Promise<AudioEngineModuleLike>): AudioDecodeEngine;
+/**
+ * Engine loader over the platform AssetService: the adapter serves
+ * assets/audio-engine/* (chrome: web_accessible_resources, obsidian:
+ * blob URLs, web: static files) and this resolves + imports them.
+ */
+export declare function createAssetAudioEngine(ctx: HostContext, importModule?: (url: string) => Promise<unknown>): AudioDecodeEngine;
+/** Encode interleaved float32 PCM as a 16-bit little-endian WAV file. */
+export declare function encodeWavFromFloat32(pcm: Float32Array, channels: number, sampleRate: number): Uint8Array;

package/dist/viewers/audio/engine.js

@@ -0,0 +1,108 @@
+// WASM audio decode/analysis engine bridge. The engine (native/audio-engine,
+// built to assets/audio-engine/audio_engine.{mjs,wasm}) decodes WAV/MP3/FLAC/
+// OGG entirely in WASM. The viewer uses it two ways:
+//   1. decode-and-remux: when the browser cannot decode a file, decode in
+//      WASM and re-encode to 16-bit PCM WAV that any browser can play.
+//   2. analyze: for large files, compute waveform peaks in WASM so WaveSurfer
+//      can render without running the whole file through decodeAudioData.
+function openAudio(module, data) {
+    const pointer = module._malloc(data.byteLength);
+    module.HEAPU8.set(data, pointer);
+    const handle = module._decode_audio(pointer, data.byteLength);
+    module._free(pointer);
+    if (!handle)
+        throw new Error('audio engine: unsupported or corrupted stream');
+    return {
+        module,
+        handle,
+        channels: module._audio_get_channels(handle),
+        sampleRate: module._audio_get_sample_rate(handle),
+        // >>> 0: the low word is a raw uint32 read back through a signed ABI.
+        frames: (module._audio_get_total_frames(handle) >>> 0)
+            + module._audio_get_total_frames_high(handle) * 2 ** 32
+    };
+}
+export function createWasmAudioEngine(loadModule) {
+    let modulePromise;
+    const module = () => (modulePromise ??= loadModule());
+    return {
+        async decode(data) {
+            const engine = await module();
+            const audio = openAudio(engine, data);
+            try {
+                const samplesPointer = engine.getValue(audio.handle, 'i32') >>> 0;
+                const length = audio.frames * audio.channels;
+                const pcm = new Float32Array(engine.HEAPF32.buffer, samplesPointer, length).slice();
+                return { sampleRate: audio.sampleRate, channels: audio.channels, frames: audio.frames, pcm };
+            }
+            finally {
+                engine._free_audio(audio.handle);
+            }
+        },
+        async analyze(data, width) {
+            const engine = await module();
+            const audio = openAudio(engine, data);
+            try {
+                const columns = Math.max(1, Math.floor(width));
+                const peaksPointer = engine._generate_peaks(audio.handle, columns) >>> 0;
+                if (!peaksPointer)
+                    throw new Error('audio engine: peaks generation failed');
+                const peaks = [...new Float32Array(engine.HEAPF32.buffer, peaksPointer, columns)];
+                engine._free_buffer(peaksPointer);
+                return {
+                    sampleRate: audio.sampleRate,
+                    channels: audio.channels,
+                    duration: audio.sampleRate > 0 ? audio.frames / audio.sampleRate : 0,
+                    peaks
+                };
+            }
+            finally {
+                engine._free_audio(audio.handle);
+            }
+        }
+    };
+}
+/**
+ * Engine loader over the platform AssetService: the adapter serves
+ * assets/audio-engine/* (chrome: web_accessible_resources, obsidian:
+ * blob URLs, web: static files) and this resolves + imports them.
+ */
+export function createAssetAudioEngine(ctx, importModule = (url) => import(/* @vite-ignore */ /* webpackIgnore: true */ url)) {
+    return createWasmAudioEngine(async () => {
+        const [moduleUrl, wasmUrl] = await Promise.all([
+            ctx.assets.resolveAssetUrl('audio-engine/audio_engine.mjs'),
+            ctx.assets.resolveAssetUrl('audio-engine/audio_engine.wasm')
+        ]);
+        const factory = (await importModule(moduleUrl)).default;
+        return factory({ locateFile: () => wasmUrl });
+    });
+}
+/** Encode interleaved float32 PCM as a 16-bit little-endian WAV file. */
+export function encodeWavFromFloat32(pcm, channels, sampleRate) {
+    const dataSize = pcm.length * 2;
+    const buffer = new ArrayBuffer(44 + dataSize);
+    const view = new DataView(buffer);
+    const writeAscii = (offset, text) => {
+        for (let i = 0; i < text.length; i++)
+            view.setUint8(offset + i, text.charCodeAt(i));
+    };
+    writeAscii(0, 'RIFF');
+    view.setUint32(4, 36 + dataSize, true);
+    writeAscii(8, 'WAVE');
+    writeAscii(12, 'fmt ');
+    view.setUint32(16, 16, true);
+    view.setUint16(20, 1, true); // PCM
+    view.setUint16(22, channels, true);
+    view.setUint32(24, sampleRate, true);
+    view.setUint32(28, sampleRate * channels * 2, true);
+    view.setUint16(32, channels * 2, true);
+    view.setUint16(34, 16, true);
+    writeAscii(36, 'data');
+    view.setUint32(40, dataSize, true);
+    const samples = new Int16Array(buffer, 44);
+    for (let i = 0; i < pcm.length; i++) {
+        const clamped = Math.max(-1, Math.min(1, pcm[i]));
+        samples[i] = Math.round(clamped < 0 ? clamped * 0x8000 : clamped * 0x7fff);
+    }
+    return new Uint8Array(buffer);
+}

package/dist/viewers/audio/index.d.ts

@@ -0,0 +1,92 @@
+import type { HostContext } from '../../host/index.js';
+import { type MediaMountOptions } from '../media.js';
+import { type ViewerHandle, type ViewerInput } from '../types.js';
+import { type AudioDecodeEngine } from './engine.js';
+export { parseAudioInfo } from '../../parsers/audio/index.js';
+export { audioViewerCss } from './styles.js';
+export { createAudioController, AUDIO_MIN_ZOOM, AUDIO_MAX_ZOOM, type AudioAction, type AudioController, type AudioViewState, type AudioVisualization } from './controller.js';
+export { createAssetAudioEngine, createWasmAudioEngine, encodeWavFromFloat32, type AudioAnalysis, type AudioDecodeEngine, type AudioEngineModuleLike, type DecodedAudio } from './engine.js';
+export type AudioViewerContext = HostContext;
+export interface AudioPluginHandle {
+    destroy?(): void;
+}
+export interface AudioRegionHandle {
+    id: string;
+    start: number;
+    end: number;
+    play(): void;
+    remove(): void;
+}
+export interface AudioRegionsHandle extends AudioPluginHandle {
+    on(event: string, callback: (region: AudioRegionHandle) => void): unknown;
+    clearRegions(): void;
+    getRegions(): AudioRegionHandle[];
+    enableDragSelection(options: Record<string, unknown>): unknown;
+}
+export interface AudioWaveSurferHandle {
+    on(event: string, callback: (payload?: unknown) => void): unknown;
+    registerPlugin<T extends AudioPluginHandle>(plugin: T): T;
+    playPause(): void | Promise<void>;
+    stop(): void;
+    setTime(seconds: number): void;
+    setVolume(volume: number): void;
+    zoom(pxPerSec: number): void;
+    getDuration(): number;
+    getCurrentTime(): number;
+    getDecodedData(): {
+        numberOfChannels: number;
+        sampleRate: number;
+        duration: number;
+    } | null;
+    destroy(): void;
+}
+export interface AudioWaveSurferCreateOptions {
+    container: HTMLElement;
+    url: string;
+    height: number;
+    normalize: boolean;
+    waveColor: string;
+    progressColor: string;
+    cursorColor: string;
+    /** Precomputed peaks + duration: WaveSurfer then skips decodeAudioData
+     *  and streams playback through a media element (large-file mode). */
+    peaks?: number[][];
+    duration?: number;
+}
+export interface AudioWaveformLibrary {
+    createWaveSurfer(options: AudioWaveSurferCreateOptions): AudioWaveSurferHandle;
+    createRegions?(): AudioRegionsHandle;
+    createTimeline?(options: {
+        container: HTMLElement;
+    }): AudioPluginHandle;
+    createSpectrogram?(options: {
+        container: HTMLElement;
+        labels: boolean;
+        height: number;
+        splitChannels: boolean;
+    }): AudioPluginHandle;
+}
+export interface AudioViewerDeps {
+    loadWaveform(): Promise<AudioWaveformLibrary>;
+    /** Optional WASM decode/analysis engine (viewers/audio/engine.ts):
+     *  browser-decode failures fall back to it, and files larger than
+     *  `engineAnalyzeBytes` get WASM-computed peaks instead of a full
+     *  browser decode. */
+    engine?: AudioDecodeEngine;
+}
+export interface AudioMountOptions extends MediaMountOptions {
+    /** Waveform engine (WaveSurfer). Absent → basic `<audio>` player. */
+    deps?: AudioViewerDeps;
+    /** Files above this size use engine peak analysis (default 50 MiB). */
+    engineAnalyzeBytes?: number;
+}
+export declare const AUDIO_VIEWER_META: {
+    id: string;
+    displayNameKey: string;
+    extensions: string[];
+    priority: number;
+    requiredServices: readonly [];
+    optionalServices: readonly [];
+    inputOwnership: "borrows";
+};
+export declare function mountAudioViewer(input: ViewerInput, container: HTMLElement, ctx: AudioViewerContext, options?: AudioMountOptions): Promise<ViewerHandle>;