@miraiclip/audio-sources

npm install @miraiclip/audio-sources

FunctionsCopy Anchor Link

audioAssetPayloadCopy Anchor Link

The asset/add payload for a resolved file, provenance included.

function audioAssetPayload(resolved: ResolvedAudio, id: string): {
    attribution?: string;
    license?: _miraiclip_core.AssetLicense;
    durationUs?: number;
    id: string;
    kind: "audio";
    src: string;
    name: string;
    source: _miraiclip_core.AssetSource;
}

audioToolDefinitionsCopy Anchor Link

function audioToolDefinitions(library: AudioLibrary, options?: AudioToolDefinitionsOptions): unknown[]

Guides: Editing assistant, Audio

createAudioLibraryCopy Anchor Link

function createAudioLibrary(providers: AudioProvider[], options?: CreateAudioLibraryOptions): AudioLibrary

Guides: Audio

createGeneratorHandlerCopy Anchor Link

Returns a Fetch-API handler; resolves null for paths it doesn't own.

function createGeneratorHandler(generators: AudioGenerator[], options?: GeneratorHandlerOptions): (request: Request) => Promise<Response | null>

Guides: Audio

creditLineCopy Anchor Link

A conventional credit line: “Title” by Creator (License).

function creditLine(title: string, creator: string | undefined, license: AssetLicense | null, landingUrl?: string): string

Guides: Audio

defineGeneratorCopy Anchor Link

Check an adapter's shape once, at registration (typos fail early).

function defineGenerator<G extends AudioGenerator>(generator: G): G

Guides: Audio

describeGeneratorCopy Anchor Link

The serializable description of a generator (what a backend advertises).

function describeGenerator(generator: AudioGenerator): GeneratorInfo

elevenLabsGeneratorCopy Anchor Link

function elevenLabsGenerator(options?: ElevenLabsGeneratorOptions): AudioGenerator

Guides: Audio

freesoundItemCopy Anchor Link

function freesoundItem(raw: FreesoundSound, provider?: string): AudioItem

freesoundProviderCopy Anchor Link

function freesoundProvider(options?: FreesoundProviderOptions): AudioProvider

Guides: Audio

httpProviderCopy Anchor Link

function httpProvider(options: HttpProviderOptions): AudioProvider

Guides: Audio

importAudioCopy Anchor Link

Add a resolved file to a project in ONE transaction (one undo step): asset/add with source, license and attribution, then clip/add on an audio track. If the app copies remote files into its own storage, do that first and pass { ...resolved, src: storedUrl }.

function importAudio(project: Project, resolved: ResolvedAudio, options?: ImportAudioOptions): ImportAudioResult

Guides: Asset import, Collaboration, Audio

nameForCopy Anchor Link

A readable asset name from the request.

function nameFor(request: GenerateRequest): string

openverseItemCopy Anchor Link

function openverseItem(raw: OpenverseAudio, provider?: string): AudioItem

openverseProviderCopy Anchor Link

function openverseProvider(options?: OpenverseProviderOptions): AudioProvider

Guides: Audio

parseCreativeCommonsCopy Anchor Link

Creative Commons → AssetLicense. Accepts the forms providers use: codes ("by-nc", "cc0", "pdm"), names ("Attribution Noncommercial", "Creative Commons 0") and deed URLs ("https://creativecommons.org/licenses/by-sa/4.0/").

• commercial: false for any NC variant.
• attributionRequired: false for CC0 and the Public Domain Mark. Returns null for anything unrecognized — callers treat that as unlicensed.

function parseCreativeCommons(input: string | null | undefined, version?: string | null): AssetLicense | null

Guides: Audio

remoteGeneratorCopy Anchor Link

One remote generator from its advertised info.

function remoteGenerator(endpoint: string, info: GeneratorInfo, options?: RemoteGeneratorsOptions): AudioGenerator

remoteGeneratorsCopy Anchor Link

The generators a backend serves, as browser-side AudioGenerators.

function remoteGenerators(endpoint: string, options?: RemoteGeneratorsOptions): Promise<AudioGenerator[]>

Guides: Audio

runAudioToolCopy Anchor Link

function runAudioTool(name: string, input: unknown, ctx: RunAudioToolContext): Promise<AudioToolResult>

Guides: Editing assistant, Audio

startGenerationCopy Anchor Link

Run a generator as a cancellable job and normalize its output into ResolvedAudio.

function startGeneration(generator: AudioGenerator, request: GenerateRequest, options?: StartGenerationOptions): GenerationJob

staticProviderCopy Anchor Link

function staticProvider(options: StaticProviderOptions): AudioProvider

Guides: Audio

toneGeneratorCopy Anchor Link

function toneGenerator(options?: ToneGeneratorOptions): AudioGenerator

Guides: Audio

validateRequestCopy Anchor Link

Reject requests a generator can't take, with messages fit for users and agents.

function validateRequest(generator: Pick<AudioGenerator, "id" | "kinds" | "limits">, request: GenerateRequest): string | null

ClassesCopy Anchor Link

AudioSourceErrorCopy Anchor Link

A provider request failed (network, HTTP status, or an unexpected payload).

Extends Error.

new AudioSourceError(provider: string, message: string, status?: number | undefined)

ConstantsCopy Anchor Link

AUDIO_TOOL_NAMESCopy Anchor Link

const AUDIO_TOOL_NAMES: readonly ["search_audio", "add_audio", "generate_audio", "list_voices"]

InterfacesCopy Anchor Link

AudioGeneratorCopy Anchor Link

AudioItemCopy Anchor Link

One search result: enough to list, preview and credit it.

Guides: Audio

AudioLibraryCopy Anchor Link

The set of providers (search) and generators (AI) an app offers. UIs, the AI tools and the MCP server all read from one library, so adding a source or swapping a generation vendor never touches them. Items from searches are remembered, so an agent can add by id.

AudioProviderCopy Anchor Link

One searchable audio source: a stock library, an in-app catalog, your backend. (Generation services are AudioGenerators — see generate/types.) Network-facing adapters take fetch and a base URL so apps can route them through their own backend (keys stay server-side, CORS is a non-issue).

AudioProviderCapabilitiesCopy Anchor Link

AudioQueryCopy Anchor Link

A search. Filters a provider can't apply server-side are applied to the page it returns.

Guides: Audio

AudioSearchResultCopy Anchor Link

AudioToolDefinitionsOptionsCopy Anchor Link

The AI surface: audio search, import and generation as LLM tools, the same shape as core's toToolDefinitions. runAudioTool executes a tool call against a library and a project; results are small JSON objects meant to go straight back to the model. Adding audio still lands as ordinary core commands (one transaction), so undo, history and collaboration behave as usual.

CreateAudioLibraryOptionsCopy Anchor Link

ElevenLabsGeneratorOptionsCopy Anchor Link

FreesoundProviderOptionsCopy Anchor Link

FreesoundSoundCopy Anchor Link

GeneratedAudioCopy Anchor Link

The bytes (or a fetchable URL) a generator produced, plus what it is.

GeneratedResultCopy Anchor Link

GenerateOptionsCopy Anchor Link

GenerateProgressCopy Anchor Link

GenerationJobCopy Anchor Link

A generation in progress. One shape for sync and job-based vendors.

GeneratorHandlerOptionsCopy Anchor Link

GeneratorLimitsCopy Anchor Link

GeneratorModelCopy Anchor Link

GeneratorTermsCopy Anchor Link

GeneratorVoiceCopy Anchor Link

HttpProviderOptionsCopy Anchor Link

ImportAudioOptionsCopy Anchor Link

ImportAudioResultCopy Anchor Link

MusicRequestCopy Anchor Link

OpenverseAudioCopy Anchor Link

The parts of an Openverse audio result this adapter reads.

OpenverseProviderOptionsCopy Anchor Link

RemoteGeneratorsOptionsCopy Anchor Link

ResolvedAudioCopy Anchor Link

A playable file plus everything asset/add records about it. src is a URL the renderer can fetch (Range + CORS) — apps that copy remote files into their own storage replace it before importing (see importAudio).

RunAudioToolContextCopy Anchor Link

SfxRequestCopy Anchor Link

The vendor-neutral generation contract. Nothing here names a service: an ElevenLabs, OpenAI, Google, ByteDance or self-hosted adapter is a small object implementing AudioGenerator. Common intent goes in the request; anything vendor-specific goes in options.params, described by the adapter's paramsSchema so UIs and AI tools can offer it without code.

StartGenerationOptionsCopy Anchor Link

Extends Omit<GenerateOptions, "signal" \| "onProgress">.

StaticAudioEntryCopy Anchor Link

StaticProviderOptionsCopy Anchor Link

ToneGeneratorOptionsCopy Anchor Link

VoiceRequestCopy Anchor Link

TypesCopy Anchor Link

AudioKindCopy Anchor Link

What a sound is for. Providers map their own categories onto these.

type AudioKind = "music" | "sfx" | "voice";

AudioToolNameCopy Anchor Link

type AudioToolName = (typeof AUDIO_TOOL_NAMES)[number];

AudioToolResultCopy Anchor Link

type AudioToolResult = {
    ok: true;
    result: unknown;
} | {
    ok: false;
    error: string;
};

FetchLikeCopy Anchor Link

type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;

GenerateRequestCopy Anchor Link

type GenerateRequest = SfxRequest | MusicRequest | VoiceRequest;

GenerationStatusCopy Anchor Link

type GenerationStatus = "running" | "done" | "failed" | "canceled";

GeneratorInfoCopy Anchor Link

Everything about a generator except generate — what a backend advertises.

type GeneratorInfo = Omit<AudioGenerator, "generate" | "voices"> & {
    hasVoices: boolean;
};

ParamsSchemaCopy Anchor Link

A JSON Schema object describing options.params for one kind.

type ParamsSchema = {
    type: "object";
    properties: Record<string, Record<string, unknown>>;
    required?: string[];
    additionalProperties?: boolean;
};