@aelionsdk/sdk 0.1.0-beta.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FoyonaCZY and AelionSDK contributors
+
+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,63 @@
+# `@aelionsdk/sdk`
+
+Browser-first video editing, preview, playback and export APIs for AelionSDK.
+
+## Install the public Beta
+
+```bash
+npm install @aelionsdk/sdk@next
+npm install --save-dev @aelionsdk/vite-plugin@next vite
+```
+
+`next` currently resolves to `0.1.0-beta.1`. Pin the exact version after
+validation instead of following a moving prerelease tag.
+
+## Vite setup
+
+```ts
+// vite.config.ts
+import { aelion } from '@aelionsdk/vite-plugin';
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+  plugins: [aelion()],
+});
+```
+
+The plugin emits the Renderer Worker, Export Worker and both AudioWorklet
+entries. Non-Vite hosts can deploy those entries themselves and pass their
+URLs through `AelionSessionOptions.runtimeAssets`.
+
+## Start a session
+
+```ts
+import { Aelion, ProductionMediaProvider, createProject } from '@aelionsdk/sdk';
+
+const media = new ProductionMediaProvider();
+const session = await Aelion.createSession({ media });
+
+const builder = createProject({
+  projectId: 'project_main',
+  title: 'My project',
+  width: 1920,
+  height: 1080,
+  frameRate: { numerator: 30, denominator: 1 },
+  sampleRate: 48_000,
+});
+
+await session.loadProject(builder.build());
+```
+
+See the [AelionSDK documentation](https://foyonaczy.github.io/AelionSDK/) for
+media registration, Composition APIs, preview, local export, persistent
+checkpoints, deployment headers and capability preflight.
+
+## Beta contract
+
+The Beta is tested on the automated Chromium and Firefox matrix. Playwright
+WebKit and a mobile viewport cover public capability and fallback contracts;
+physical Safari, iOS and Android devices are not yet certified. Local color
+execution is RGBA8 SDR. Public APIs may still change before the first stable
+release and will be recorded in the repository changelog and migration guide.
+
+AelionSDK is licensed under the MIT License.

package/dist/audio-controller.d.ts

@@ -0,0 +1,25 @@
+import { type LoudnessReport, type SilenceDetectionResult, type WaveformPeakResult } from '@aelionsdk/audio';
+import type { AelionProject } from '@aelionsdk/project-schema';
+import type { RenderIr } from '@aelionsdk/render-ir';
+import type { TransactionBuilder, TransactionCommit } from '@aelionsdk/transaction';
+import type { AelionAudioAnalysisOptions, AelionAudioApi, AelionAudioMasteringOptions, AelionAudioRemoveSilenceOptions, AelionAudioRemoveSilenceResult, AelionAudioWaveformOptions, AelionMediaProvider } from './types.js';
+interface AudioControllerHost {
+    readonly ir: () => RenderIr;
+    readonly project: () => Readonly<AelionProject>;
+    readonly media: () => AelionMediaProvider;
+    readonly revision: () => bigint;
+    readonly edit: (label: string, callback: (transaction: TransactionBuilder) => void) => TransactionCommit;
+}
+export declare class SessionAudioController implements AelionAudioApi {
+    private readonly host;
+    constructor(host: AudioControllerHost);
+    getMastering(): AelionAudioMasteringOptions | undefined;
+    configureMastering(options: AelionAudioMasteringOptions): TransactionCommit;
+    analyze(options?: AelionAudioAnalysisOptions): Promise<LoudnessReport>;
+    waveform(options?: AelionAudioWaveformOptions): Promise<WaveformPeakResult>;
+    detectSilence(options: AelionAudioRemoveSilenceOptions): Promise<SilenceDetectionResult>;
+    removeSilence(options: AelionAudioRemoveSilenceOptions): Promise<AelionAudioRemoveSilenceResult>;
+}
+export declare function projectAudioMastering(project: Readonly<AelionProject>, sequenceId: string): AelionAudioMasteringOptions | undefined;
+export {};
+//# sourceMappingURL=audio-controller.d.ts.map

package/dist/audio-controller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audio-controller.d.ts","sourceRoot":"","sources":["../src/audio-controller.ts"],"names":[],"mappings":"AAAA,OAAO,EAKL,KAAK,cAAc,EACnB,KAAK,sBAAsB,EAC3B,KAAK,kBAAkB,EACxB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,KAAK,EAAE,aAAa,EAAc,MAAM,2BAA2B,CAAC;AAC3E,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,KAAK,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAEpF,OAAO,KAAK,EACV,0BAA0B,EAC1B,cAAc,EACd,2BAA2B,EAC3B,+BAA+B,EAC/B,8BAA8B,EAC9B,0BAA0B,EAC1B,mBAAmB,EACpB,MAAM,YAAY,CAAC;AAIpB,UAAU,mBAAmB;IAC3B,QAAQ,CAAC,EAAE,EAAE,MAAM,QAAQ,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,QAAQ,CAAC,aAAa,CAAC,CAAC;IAChD,QAAQ,CAAC,KAAK,EAAE,MAAM,mBAAmB,CAAC;IAC1C,QAAQ,CAAC,QAAQ,EAAE,MAAM,MAAM,CAAC;IAChC,QAAQ,CAAC,IAAI,EAAE,CACb,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,CAAC,WAAW,EAAE,kBAAkB,KAAK,IAAI,KAChD,iBAAiB,CAAC;CACxB;AAwED,qBAAa,sBAAuB,YAAW,cAAc;IACxC,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAAJ,IAAI,EAAE,mBAAmB;IAEtD,YAAY,IAAI,2BAA2B,GAAG,SAAS;IAKvD,kBAAkB,CAAC,OAAO,EAAE,2BAA2B,GAAG,iBAAiB;IAoBrE,OAAO,CAAC,OAAO,GAAE,0BAA+B,GAAG,OAAO,CAAC,cAAc,CAAC;IAiBhF,QAAQ,CAAC,OAAO,GAAE,0BAA+B,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAgBzE,aAAa,CACxB,OAAO,EAAE,+BAA+B,GACvC,OAAO,CAAC,sBAAsB,CAAC;IAkCrB,aAAa,CACxB,OAAO,EAAE,+BAA+B,GACvC,OAAO,CAAC,8BAA8B,CAAC;CA0H3C;AAED,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,QAAQ,CAAC,aAAa,CAAC,EAChC,UAAU,EAAE,MAAM,GACjB,2BAA2B,GAAG,SAAS,CAEzC"}

package/dist/audio-controller.js

@@ -0,0 +1,235 @@
+import { StreamingLoudnessAnalyzer, buildWaveformPeaks, detectSilence, renderIrAudio, } from '@aelionsdk/audio';
+import { sampleBoundaryUs, sampleIndexAtTime } from '@aelionsdk/core';
+const MASTERING_EXTENSION = 'aelion.audio.mastering';
+function channelCount(layout) {
+    if (layout === 'mono')
+        return 1;
+    if (layout === 'stereo')
+        return 2;
+    if (layout === '5.1')
+        return 6;
+    throw new RangeError(`Unsupported channel layout ${layout}`);
+}
+function totalFrames(ir) {
+    return sampleIndexAtTime(ir.durationUs, ir.sampleRate, 'floor');
+}
+function readSelection(host, options, startFrame, frameCount, signal) {
+    const ir = host.ir();
+    return renderIrAudio({
+        ir,
+        startFrame,
+        frameCount,
+        channelCount: channelCount(ir.channelLayout),
+        source: host.media(),
+        ...(options.trackIds === undefined ? {} : { trackIds: options.trackIds }),
+        ...(options.itemIds === undefined ? {} : { itemIds: options.itemIds }),
+        ...(signal === undefined ? {} : { signal }),
+    });
+}
+function assertAudioItem(project, itemId) {
+    const item = project.items[itemId];
+    if (item === undefined)
+        throw new ReferenceError(`Unknown Item: ${itemId}`);
+    if (item.type !== 'audio')
+        throw new TypeError(`${itemId} is not an audio Item`);
+    return item;
+}
+function masteringFrom(project, sequenceId) {
+    const sequence = project.sequences[sequenceId];
+    const extensions = sequence?.extensions;
+    const value = extensions !== null && typeof extensions === 'object' && !Array.isArray(extensions)
+        ? extensions[MASTERING_EXTENSION]
+        : undefined;
+    return value !== null && typeof value === 'object' && !Array.isArray(value)
+        ? structuredClone(value)
+        : undefined;
+}
+export class SessionAudioController {
+    host;
+    constructor(host) {
+        this.host = host;
+    }
+    getMastering() {
+        const ir = this.host.ir();
+        return masteringFrom(this.host.project(), ir.sequenceId);
+    }
+    configureMastering(options) {
+        const ir = this.host.ir();
+        const project = this.host.project();
+        const sequence = project.sequences[ir.sequenceId];
+        if (sequence === undefined)
+            throw new ReferenceError(`Unknown Sequence: ${ir.sequenceId}`);
+        const currentExtensions = sequence.extensions !== null &&
+            typeof sequence.extensions === 'object' &&
+            !Array.isArray(sequence.extensions)
+            ? sequence.extensions
+            : {};
+        const extensions = {
+            ...currentExtensions,
+            [MASTERING_EXTENSION]: structuredClone(options),
+        };
+        return this.host.edit('Configure audio mastering', transaction => {
+            transaction.setField('sequences', ir.sequenceId, ['extensions'], extensions);
+        });
+    }
+    async analyze(options = {}) {
+        const ir = this.host.ir();
+        const channels = channelCount(ir.channelLayout);
+        const analyzer = new StreamingLoudnessAnalyzer(ir.sampleRate, channels);
+        const frames = totalFrames(ir);
+        const blockFrames = options.blockFrames ?? 8_192;
+        for (let startFrame = 0; startFrame < frames; startFrame += blockFrames) {
+            const frameCount = Math.min(blockFrames, frames - startFrame);
+            analyzer.process(await readSelection(this.host, options, startFrame, frameCount, options.signal));
+            options.onProgress?.((startFrame + frameCount) / Math.max(1, frames));
+        }
+        if (frames === 0)
+            options.onProgress?.(1);
+        return analyzer.finish();
+    }
+    waveform(options = {}) {
+        const ir = this.host.ir();
+        const channels = channelCount(ir.channelLayout);
+        return buildWaveformPeaks({
+            sampleRate: ir.sampleRate,
+            channelCount: channels,
+            totalFrames: totalFrames(ir),
+            ...(options.windowFrames === undefined ? {} : { windowFrames: options.windowFrames }),
+            ...(options.maxPoints === undefined ? {} : { maxPoints: options.maxPoints }),
+            ...(options.signal === undefined ? {} : { signal: options.signal }),
+            ...(options.onProgress === undefined ? {} : { onProgress: options.onProgress }),
+            readFrames: (startFrame, frameCount, signal) => readSelection(this.host, options, startFrame, frameCount, signal),
+        });
+    }
+    async detectSilence(options) {
+        const ir = this.host.ir();
+        const project = this.host.project();
+        const item = assertAudioItem(project, options.itemId);
+        const channels = channelCount(ir.channelLayout);
+        const itemStartFrame = sampleIndexAtTime(item.range.startUs, ir.sampleRate, 'floor');
+        const itemEndFrame = sampleIndexAtTime(item.range.startUs + item.range.durationUs, ir.sampleRate, 'floor');
+        return detectSilence({
+            sampleRate: ir.sampleRate,
+            channelCount: channels,
+            totalFrames: itemEndFrame - itemStartFrame,
+            ...(options.thresholdDb === undefined ? {} : { thresholdDb: options.thresholdDb }),
+            ...(options.minimumSilenceUs === undefined
+                ? {}
+                : { minimumSilenceUs: options.minimumSilenceUs }),
+            ...(options.paddingUs === undefined ? {} : { paddingUs: options.paddingUs }),
+            ...(options.windowFrames === undefined ? {} : { windowFrames: options.windowFrames }),
+            ...(options.signal === undefined ? {} : { signal: options.signal }),
+            ...(options.onProgress === undefined ? {} : { onProgress: options.onProgress }),
+            readFrames: (startFrame, frameCount, signal) => readSelection(this.host, { itemIds: [item.id] }, itemStartFrame + startFrame, frameCount, signal),
+        });
+    }
+    async removeSilence(options) {
+        const baseRevision = this.host.revision();
+        const project = this.host.project();
+        const ir = this.host.ir();
+        const item = assertAudioItem(project, options.itemId);
+        if (item.linkGroupId !== undefined) {
+            throw new TypeError('Unlink an audio Item before removing silence');
+        }
+        if ((item.markerIds?.length ?? 0) > 0 || item.materialInstanceIds.length > 0) {
+            throw new TypeError('Audio Item markers/effects require an explicit split ownership policy');
+        }
+        if (Object.values(project.transitions).some(value => value.fromItemId === item.id || value.toItemId === item.id)) {
+            throw new TypeError('Remove transitions attached to an audio Item before removing silence');
+        }
+        if (item.source.timeMapping.type !== 'linear') {
+            throw new TypeError('Silence removal currently requires a linear audio TimeMap');
+        }
+        const mapping = item.source.timeMapping;
+        if (mapping.reverse ||
+            mapping.rate.numerator !== mapping.rate.denominator ||
+            mapping.boundary !== 'hold') {
+            throw new TypeError('Silence removal requires forward 1x hold-boundary audio');
+        }
+        const track = project.tracks[item.trackId];
+        if (track === undefined)
+            throw new ReferenceError(`Unknown Track: ${item.trackId}`);
+        const originalEndUs = item.range.startUs + item.range.durationUs;
+        const overlapping = track.itemIds
+            .filter(id => id !== item.id)
+            .flatMap(id => {
+            const candidate = project.items[id];
+            if (candidate === undefined)
+                return [];
+            const endUs = candidate.range.startUs + candidate.range.durationUs;
+            return candidate.range.startUs < originalEndUs && endUs > item.range.startUs
+                ? [candidate.id]
+                : [];
+        });
+        if (overlapping.length > 0) {
+            throw new TypeError('Silence compaction requires a non-overlapping audio Item');
+        }
+        const detection = await this.detectSilence(options);
+        if (this.host.revision() !== baseRevision) {
+            throw new Error('Project revision changed while silence detection was running');
+        }
+        if (detection.removedFrames === 0) {
+            throw new RangeError('No removable silence was detected');
+        }
+        const kept = detection.nonSilent;
+        const nextItemId = track.itemIds[track.itemIds.indexOf(item.id) + 1];
+        const createdIds = [];
+        let cursorUs = item.range.startUs;
+        const segmentValues = kept.map((range, index) => {
+            const localStartUs = sampleBoundaryUs(range.startFrame, ir.sampleRate);
+            const localEndUs = sampleBoundaryUs(range.startFrame + range.frameCount, ir.sampleRate);
+            const durationUs = Math.max(1, localEndUs - localStartUs);
+            const id = index === 0 ? item.id : `${item.id}_audible_${baseRevision.toString()}_${index.toString()}`;
+            const value = structuredClone(item);
+            value.id = id;
+            value.range = { startUs: cursorUs, durationUs };
+            value.source.sourceRange = {
+                startUs: item.source.sourceRange.startUs + localStartUs,
+                durationUs,
+            };
+            cursorUs += durationUs;
+            return value;
+        });
+        const removedUs = item.range.durationUs - (cursorUs - item.range.startUs);
+        const laterItems = track.itemIds.flatMap(id => {
+            const value = project.items[id];
+            return value !== undefined && value.id !== item.id && value.range.startUs >= originalEndUs
+                ? [value]
+                : [];
+        });
+        const laterTransitions = Object.values(project.transitions).filter(value => value.trackId === track.id && value.range.startUs >= originalEndUs);
+        const commit = this.host.edit('Remove audio silence', transaction => {
+            if (segmentValues.length === 0) {
+                transaction.listRemove('tracks', track.id, ['itemIds'], item.id);
+                transaction.deleteEntity('items', item.id);
+            }
+            else {
+                const first = segmentValues[0];
+                if (first === undefined)
+                    throw new Error('Missing first audible segment');
+                transaction.setField('items', item.id, ['range'], first.range);
+                transaction.setField('items', item.id, ['source', 'sourceRange'], first.source.sourceRange);
+                for (const segment of segmentValues.slice(1)) {
+                    transaction.createEntity('items', segment.id, segment);
+                    transaction.listInsert('tracks', track.id, ['itemIds'], segment.id, nextItemId);
+                    createdIds.push(segment.id);
+                }
+            }
+            for (const later of laterItems) {
+                transaction.setField('items', later.id, ['range', 'startUs'], later.range.startUs - removedUs);
+            }
+            for (const transition of laterTransitions) {
+                transaction.setField('transitions', transition.id, ['range', 'startUs'], transition.range.startUs - removedUs);
+            }
+        });
+        return {
+            commit,
+            detection,
+            itemIds: segmentValues.length === 0 ? [] : [item.id, ...createdIds],
+            removedUs,
+        };
+    }
+}
+export function projectAudioMastering(project, sequenceId) {
+    return masteringFrom(project, sequenceId);
+}

package/dist/audio-mastering.d.ts

@@ -0,0 +1,27 @@
+import { type LoudnessReport } from '@aelionsdk/audio';
+import type { RenderIr } from '@aelionsdk/render-ir';
+import type { AelionAudioMasteringOptions, AelionMediaProvider } from './types.js';
+export interface MasteredAudioRequest {
+    readonly startFrame: number;
+    readonly frameCount: number;
+    readonly channelCount: number;
+}
+export interface AudioMasteringReport {
+    readonly inputLoudness?: LoudnessReport;
+    readonly appliedGainDb: number;
+    readonly limiterEnabled: boolean;
+    readonly duckingRules: number;
+}
+export interface MasteredAudioRenderer {
+    readonly report: AudioMasteringReport;
+    readonly render: (request: MasteredAudioRequest, signal?: AbortSignal) => Promise<Float32Array>;
+}
+export interface CreateMasteredAudioRendererOptions {
+    readonly ir: RenderIr;
+    readonly source: AelionMediaProvider;
+    readonly processing?: AelionAudioMasteringOptions;
+    readonly signal?: AbortSignal;
+    readonly onAnalysisProgress?: (progress: number) => void;
+}
+export declare function createMasteredAudioRenderer(options: CreateMasteredAudioRendererOptions): Promise<MasteredAudioRenderer>;
+//# sourceMappingURL=audio-mastering.d.ts.map

package/dist/audio-mastering.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audio-mastering.d.ts","sourceRoot":"","sources":["../src/audio-mastering.ts"],"names":[],"mappings":"AAAA,OAAO,EAKL,KAAK,cAAc,EACpB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAErD,OAAO,KAAK,EAAE,2BAA2B,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAEnF,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,aAAa,CAAC,EAAE,cAAc,CAAC;IACxC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IACjC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,MAAM,EAAE,oBAAoB,CAAC;IACtC,QAAQ,CAAC,MAAM,EAAE,CAAC,OAAO,EAAE,oBAAoB,EAAE,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,YAAY,CAAC,CAAC;CACjG;AAED,MAAM,WAAW,kCAAkC;IACjD,QAAQ,CAAC,EAAE,EAAE,QAAQ,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,mBAAmB,CAAC;IACrC,QAAQ,CAAC,UAAU,CAAC,EAAE,2BAA2B,CAAC;IAClD,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAC9B,QAAQ,CAAC,kBAAkB,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;CAC1D;AAuCD,wBAAsB,2BAA2B,CAC/C,OAAO,EAAE,kCAAkC,GAC1C,OAAO,CAAC,qBAAqB,CAAC,CA2IhC"}

package/dist/audio-mastering.js

@@ -0,0 +1,160 @@
+import { SidechainDucker, StreamingLoudnessAnalyzer, TruePeakLimiter, renderIrAudio, } from '@aelionsdk/audio';
+import { sampleIndexAtTime, throwIfAborted } from '@aelionsdk/core';
+function channelCountForIr(ir) {
+    if (ir.channelLayout === 'mono')
+        return 1;
+    if (ir.channelLayout === 'stereo')
+        return 2;
+    if (ir.channelLayout === '5.1')
+        return 6;
+    throw new RangeError(`Unsupported channel layout ${ir.channelLayout}`);
+}
+function assertTrackSelection(ir, ids, name) {
+    for (const id of ids) {
+        const track = ir.tracks.find(value => value.id === id);
+        if (track === undefined)
+            throw new ReferenceError(`${name} references unknown Track ${id}`);
+        if (track.kind !== 'audio')
+            throw new TypeError(`${name} requires audio Tracks`);
+    }
+}
+function gainPcm(pcm, gain) {
+    if (gain === 1)
+        return pcm;
+    const output = new Float32Array(pcm.length);
+    for (let index = 0; index < pcm.length; index += 1) {
+        output[index] = (pcm[index] ?? 0) * gain;
+    }
+    return output;
+}
+function monoDetector(pcm, channels) {
+    const frames = pcm.length / channels;
+    const output = new Float32Array(frames);
+    for (let frame = 0; frame < frames; frame += 1) {
+        let sum = 0;
+        for (let channel = 0; channel < channels; channel += 1) {
+            sum += Math.abs(pcm[frame * channels + channel] ?? 0);
+        }
+        output[frame] = sum / channels;
+    }
+    return output;
+}
+export async function createMasteredAudioRenderer(options) {
+    const processing = options.processing ?? {};
+    const expectedChannelCount = channelCountForIr(options.ir);
+    const totalFrames = sampleIndexAtTime(options.ir.durationUs, options.ir.sampleRate, 'floor');
+    const raw = (request, signal, trackIds) => renderIrAudio({
+        ir: options.ir,
+        startFrame: request.startFrame,
+        frameCount: request.frameCount,
+        channelCount: request.channelCount,
+        source: options.source,
+        ...(trackIds === undefined ? {} : { trackIds }),
+        ...(signal === undefined ? {} : { signal }),
+    });
+    let inputLoudness;
+    let appliedGainDb = 0;
+    if (processing.targetLufs !== undefined) {
+        if (!Number.isFinite(processing.targetLufs)) {
+            throw new RangeError('targetLufs must be finite');
+        }
+        const analyzer = new StreamingLoudnessAnalyzer(options.ir.sampleRate, expectedChannelCount);
+        const blockFrames = 16_384;
+        for (let startFrame = 0; startFrame < totalFrames; startFrame += blockFrames) {
+            throwIfAborted(options.signal, 'Audio mastering analysis');
+            const frameCount = Math.min(blockFrames, totalFrames - startFrame);
+            analyzer.process(await raw({ startFrame, frameCount, channelCount: expectedChannelCount }, options.signal));
+            options.onAnalysisProgress?.((startFrame + frameCount) / Math.max(1, totalFrames));
+        }
+        if (totalFrames === 0)
+            options.onAnalysisProgress?.(1);
+        inputLoudness = analyzer.finish();
+        if (Number.isFinite(inputLoudness.integratedLufs)) {
+            const desired = processing.targetLufs - inputLoudness.integratedLufs;
+            const maximum = processing.maximumGainDb ?? 24;
+            if (!Number.isFinite(maximum) || maximum < 0) {
+                throw new RangeError('maximumGainDb must be a non-negative finite number');
+            }
+            appliedGainDb = Math.max(-maximum, Math.min(maximum, desired));
+        }
+    }
+    const linearGain = 10 ** (appliedGainDb / 20);
+    const ducking = (processing.ducking ?? []).map((rule, index) => {
+        assertTrackSelection(options.ir, rule.programTrackIds, `ducking[${index.toString()}].program`);
+        assertTrackSelection(options.ir, rule.sidechainTrackIds, `ducking[${index.toString()}].sidechain`);
+        const lookaheadUs = rule.lookaheadUs ?? 0;
+        if (lookaheadUs !== 0) {
+            throw new RangeError('Export ducking lookaheadUs must be zero until compensated tail flushing is enabled');
+        }
+        return {
+            rule,
+            processor: new SidechainDucker({
+                sampleRate: options.ir.sampleRate,
+                channelCount: expectedChannelCount,
+                thresholdDb: rule.thresholdDb ?? -30,
+                reductionDb: rule.reductionDb ?? -12,
+                attackUs: rule.attackUs ?? 10_000,
+                releaseUs: rule.releaseUs ?? 250_000,
+                lookaheadUs,
+            }),
+        };
+    });
+    const duckedProgramTracks = new Set();
+    for (const { rule } of ducking) {
+        for (const trackId of rule.programTrackIds) {
+            if (duckedProgramTracks.has(trackId)) {
+                throw new TypeError(`Audio Track ${trackId} cannot be a program Track in multiple ducking rules`);
+            }
+            duckedProgramTracks.add(trackId);
+        }
+    }
+    const limiterEnabled = processing.limiter !== undefined && processing.limiter !== false;
+    const limiterOptions = limiterEnabled ? processing.limiter : undefined;
+    if ((limiterOptions?.lookaheadUs ?? 0) !== 0) {
+        throw new RangeError('Export limiter lookaheadUs must be zero until compensated tail flushing is enabled');
+    }
+    let limiter;
+    let expectedStartFrame = 0;
+    return {
+        report: {
+            ...(inputLoudness === undefined ? {} : { inputLoudness }),
+            appliedGainDb,
+            limiterEnabled,
+            duckingRules: ducking.length,
+        },
+        render: async (request, signal) => {
+            if (request.channelCount !== expectedChannelCount) {
+                throw new RangeError(`Mastered audio requires ${expectedChannelCount.toString()} channels`);
+            }
+            if (request.startFrame !== expectedStartFrame) {
+                throw new RangeError('Mastered audio blocks must be requested sequentially from frame zero');
+            }
+            expectedStartFrame += request.frameCount;
+            let output = gainPcm(await raw(request, signal), linearGain);
+            for (const value of ducking) {
+                const [programRaw, sidechain] = await Promise.all([
+                    raw(request, signal, value.rule.programTrackIds),
+                    raw(request, signal, value.rule.sidechainTrackIds),
+                ]);
+                const program = gainPcm(programRaw, linearGain);
+                const ducked = value.processor.process(program, monoDetector(sidechain, request.channelCount));
+                const mixed = new Float32Array(output.length);
+                for (let index = 0; index < mixed.length; index += 1) {
+                    mixed[index] = (output[index] ?? 0) - (program[index] ?? 0) + (ducked[index] ?? 0);
+                }
+                output = mixed;
+            }
+            if (limiterEnabled) {
+                limiter ??= new TruePeakLimiter({
+                    sampleRate: options.ir.sampleRate,
+                    channelCount: request.channelCount,
+                    ceilingDbtp: limiterOptions?.ceilingDbtp ?? -1,
+                    releaseUs: limiterOptions?.releaseUs ?? 100_000,
+                    lookaheadUs: 0,
+                });
+                output = limiter.process(output);
+            }
+            return output;
+        },
+    };
+}

package/dist/composition.d.ts

@@ -0,0 +1,75 @@
+import type { JsonObject, JsonValue } from '@aelionsdk/core';
+import type { AelionProject } from '@aelionsdk/project-schema';
+import { ProjectBuilder, type AddAssetOptions, type AddCaptionClipOptions, type AddImageClipOptions, type AddMaterialInstanceOptions, type AddMediaClipOptions, type AddShapeClipOptions, type AddTextClipOptions, type AddTrackOptions, type ClipAnimatableProperty, type CreateProjectOptions, type Keyframe, type SetMaskOptions, type SetVisualOptions } from './project-builder.js';
+export interface LayerOptions {
+    readonly id?: string;
+    readonly name?: string;
+    readonly enabled?: boolean;
+    readonly locked?: boolean;
+}
+export interface MaterialOptions extends Omit<AddMaterialInstanceOptions, 'id' | 'parameters' | 'name'> {
+    readonly name?: string;
+    readonly parameters?: JsonObject;
+}
+export interface ApplyMaterialOptions {
+    readonly id?: string;
+    readonly name?: string;
+    readonly parameters?: JsonObject;
+}
+export interface CompositionTransitionOptions extends Omit<ApplyMaterialOptions, 'id'> {
+    readonly transitionId?: string;
+    readonly materialInstanceId?: string;
+    readonly atUs: number;
+    readonly durationUs: number;
+}
+/** Reusable Material definition. Each use creates a separately owned Project instance. */
+export declare class Material {
+    private readonly builder;
+    private readonly options;
+    constructor(builder: ProjectBuilder, options: MaterialOptions);
+    instantiate(options?: ApplyMaterialOptions): string;
+}
+/** Fluent handle for a Project Item. */
+export declare class Clip {
+    readonly id: string;
+    readonly layer: Layer;
+    private readonly builder;
+    constructor(id: string, layer: Layer, builder: ProjectBuilder);
+    effect(material: Material, options?: ApplyMaterialOptions): this;
+    mask(source: Clip, options?: Omit<SetMaskOptions, 'sourceItemId'>): this;
+    keyframes<T extends JsonValue>(property: ClipAnimatableProperty, values: readonly Keyframe<T>[]): this;
+    visual(options: SetVisualOptions): this;
+}
+/** Ordered Composition layer backed by a schema-valid Aelion Track. */
+export declare class Layer {
+    #private;
+    readonly kind: AddTrackOptions['kind'];
+    private readonly builder;
+    readonly id: string;
+    constructor(kind: AddTrackOptions['kind'], builder: ProjectBuilder, options?: LayerOptions);
+    video(options: Omit<AddMediaClipOptions, 'kind' | 'trackId'>): Clip;
+    audio(options: Omit<AddMediaClipOptions, 'kind' | 'trackId'>): Clip;
+    image(options: Omit<AddImageClipOptions, 'trackId'>): Clip;
+    text(options: Omit<AddTextClipOptions, 'trackId'>): Clip;
+    caption(options: Omit<AddCaptionClipOptions, 'trackId'>): Clip;
+    shape(options: Omit<AddShapeClipOptions, 'trackId'>): Clip;
+}
+/**
+ * Product-level authoring API. It keeps Composition/Layer/Clip ergonomics while
+ * producing the same portable, validator-backed Project document as ProjectBuilder.
+ */
+export declare class Composition {
+    #private;
+    constructor(options?: CreateProjectOptions);
+    get projectId(): string;
+    get sequenceId(): string;
+    asset(options: AddAssetOptions): this;
+    layer(kind: AddTrackOptions['kind'], options?: LayerOptions): Layer;
+    material(options: MaterialOptions): Material;
+    transition(from: Clip, to: Clip, material: Material, options: CompositionTransitionOptions): string;
+    build(): Readonly<AelionProject>;
+    /** Escape hatch for advanced, schema-level operations without changing document semantics. */
+    advanced(): ProjectBuilder;
+}
+export declare function createComposition(options?: CreateProjectOptions): Composition;
+//# sourceMappingURL=composition.d.ts.map

package/dist/composition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"composition.d.ts","sourceRoot":"","sources":["../src/composition.ts"],"names":[],"mappings":"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"}