> built 2026-10-14 04:26 UTC from 4223c54 (main) · arioso 0.0.24. Details: build_info.json # index.html.md # arioso Unified Python facade for AI music generation. One interface, many backends. Arioso wraps 16 AI music generation platforms — from local open-source models to commercial REST APIs — behind a single `generate()` call. ## Install ```default pip install arioso ``` ## Quick start ```python import arioso # Generate music (defaults to MusicGen, runs locally) song = arioso.generate("upbeat jazz piano") # The result is a Song object with audio data song.audio.audio_array # numpy array (for local models) song.audio.sample_rate # e.g. 32000 # Use a different platform song = arioso.generate("epic orchestral soundtrack", platform="elevenlabs", duration=30) song.audio.audio_bytes # MP3 bytes ``` ## Enhance existing audio (audio-to-audio) Beyond text-to-music, arioso can transform audio you already have – e.g. turn a plain synthesized/”MIDI” render into something richer, or re-generate music that follows an input melody. This is the `enhance()` entry point: ```python import arioso rendered = ( ... ) # a Song, a file path, bytes, an (array, sample_rate) pair, or a numpy waveform # Audio-to-audio: continue/transform the input (Stable Audio Open, local) better = arioso.enhance(rendered, "warm analog studio band", platform="stable_audio") # Subtle variation: low strength keeps the input, high lets the prompt take over # (Stable Audio 2.5 on fal.ai; needs FAL_KEY) close = arioso.enhance( rendered, "full symphony orchestra", platform="stable_audio_25", strength=0.3 ) # Remix toward style tags (ACE-Step on fal.ai) remix = arioso.enhance(rendered, "orchestral, film score, brass", platform="ace_step") # Melody-conditioned: keep the tune, take the style from the prompt (MusicGen-melody) variation = arioso.enhance(rendered, "energetic EDM", platform="musicgen") # Discover which platforms accept input audio arioso.supports_audio_input("stable_audio") # True arioso.supports_audio_input("mubert") # False ``` `enhance(audio, prompt='', *, platform='stable_audio', strength=None, as_='auto')` routes your audio into the platform’s audio-conditioning affordance (`audio_input`, `melody`, or `reference_audio`) and generates. Input audio is accepted in any form a `Song`/`AudioResult`/`bytes`/path/`(array, sample_rate)`/ numpy-waveform can take (normalized internally). Note that `stable_audio` via diffusers uses the input as an initial waveform (continuation/init) and has no `strength` knob (a value passed there is ignored with a warning); for a strength-controlled transform use `stable_audio_25`. ## Platforms 16 platforms are included, spanning local models, REST APIs, and SDK-based services: | Platform | Access | Auth | Install | |----------------------------|---------------------------------|--------------------------------------|---------------------------------------| | **MusicGen** | Local (audiocraft/transformers) | None | `pip install arioso[musicgen]` | | **Stable Audio Open** | Local (diffusers) | None | `pip install arioso[stable-audio]` | | **Harmonai** | Local (diffusers) | None | `pip install arioso[harmonai]` | | **Riffusion** | Local (diffusers) | None | `pip install arioso[riffusion]` | | **ElevenLabs** | REST API | `ELEVENLABS_API_KEY` | `pip install arioso[elevenlabs]` | | **Suno** (via sunoapi.org) | REST API | `SUNO_API_KEY` | `pip install arioso[sunoapi]` | | **Google Lyria 2** | REST (Vertex AI) | `GOOGLE_CLOUD_PROJECT` + gcloud auth | `pip install arioso[lyria2]` | | **Google Lyria RT** | WebSocket (genai SDK) | `GOOGLE_API_KEY` | `pip install arioso[lyria-rt]` | | **Mubert** | REST API | `MUBERT_PAT` | `pip install arioso[mubert]` | | **Beatoven.ai** | REST API | `BEATOVEN_API_KEY` | `pip install arioso[beatoven]` | | **Loudly** | REST API | `LOUDLY_API_KEY` | `pip install arioso[loudly]` | | **Jen** | REST API | `JEN_API_KEY` | `pip install arioso[jen]` | | **YuE** | fal.ai / local CLI | `FAL_KEY` | `pip install arioso[yue]` | | **Stable Audio 2.5** | fal.ai | `FAL_KEY` | `pip install arioso[stable-audio-25]` | | **ACE-Step** | fal.ai | `FAL_KEY` | `pip install arioso[ace-step]` | | **Udio** | Unofficial wrapper | `UDIO_AUTH_COOKIE` | `pip install arioso[udio]` | ```python # See what's available arioso.list_platforms() # ['beatoven', 'elevenlabs', 'harmonai', 'jen', 'loudly', 'lyria2', ...] # Inspect a platform's configuration arioso.get_platform_info("musicgen") ``` ### MusicGen (local, no API key) Runs on your machine. Tries `audiocraft` first, falls back to HuggingFace `transformers`. ```python song = arioso.generate( "chill lofi beats", platform="musicgen", duration=10, temperature=0.8, guidance=3.0, model="facebook/musicgen-small", # or medium, large, melody ) ``` ### ElevenLabs Needs `ELEVENLABS_API_KEY` environment variable. ```python song = arioso.generate( "dramatic film score", platform="elevenlabs", duration=60, instrumental=True, output_format="mp3_44100_128", ) # With lyrics song = arioso.generate( "pop ballad", platform="elevenlabs", lyrics="[Verse]\nWalking through the rain\n[Chorus]\nI found my way home", title="Coming Home", ) ``` ### Suno (via sunoapi.org) Needs `SUNO_API_KEY` environment variable. ```python songs = arioso.generate_many( "summer reggae vibes", platform="sunoapi", genre="reggae, tropical", instrumental=True, ) # Suno returns 2 songs per call for song in songs: print(song.title, song.audio_url) ``` ## Parameters All platforms share a common vocabulary of parameter names. Use any that the platform supports — unsupported ones are warned about and ignored. ```python song = arioso.generate( "ambient soundscape", # prompt (required) platform="musicgen", duration=15, # seconds temperature=1.2, # sampling randomness top_k=250, # top-k sampling guidance=3.0, # classifier-free guidance seed=42, # reproducibility ) ``` The full set of unified parameter names (42): | Parameter | Type | Description | |-----------------|--------|-------------------------------------| | `prompt` | str | Text description of desired music | | `duration` | float | Output length in seconds | | `lyrics` | str | Custom lyrics text | | `instrumental` | bool | Force instrumental-only output | | `genre` | str | Genre tag or category | | `title` | str | Song title | | `model` | str | Model version or variant | | `seed` | int | Random seed for reproducibility | | `guidance` | float | Classifier-free guidance scale | | `temperature` | float | Sampling randomness | | `top_k` | int | Top-k sampling parameter | | `top_p` | float | Top-p (nucleus) sampling | | `bpm` | int | Beats per minute | | `key` | str | Musical key (e.g. “C major”) | | `energy` | float | Energy/intensity level 0-1 | | `output_format` | str | Desired output format | | … | | See `arioso.AFFORDANCES` for all 40 | Each platform maps these to its native parameter names automatically. For example, `instrumental=True` becomes `make_instrumental=True` for Suno and `force_instrumental=True` for ElevenLabs. ## Output Every call returns a `Song` object: ```python song = arioso.generate("jazz piano", platform="musicgen") song.status # 'complete' song.platform # 'musicgen' song.title # '' song.metadata # {'model': 'facebook/musicgen-small', ...} # Audio is in song.audio (an AudioResult) song.audio.audio_array # numpy array (local models) song.audio.audio_bytes # raw bytes (REST APIs) song.audio.audio_url # URL string (Suno) song.audio.sample_rate # e.g. 32000 song.audio.format # 'wav', 'mp3', etc. # Shortcuts song.audio_array # same as song.audio.audio_array song.audio_bytes # same as song.audio.audio_bytes song.sample_rate # same as song.audio.sample_rate ``` Use `generate_many()` when you want all results (some platforms return multiple): ```python songs = arioso.generate_many("pop song", platform="sunoapi") # Returns list[Song] ``` ## Adding a new platform Arioso uses a plugin architecture. Each platform is a subfolder under `arioso/platforms/` with two files: ```default arioso/platforms/myplatform/ __init__.py config.py # required: declares PLATFORM_CONFIG adapter.py # optional: custom generation logic ``` ### Minimal example (REST API) For a REST API, you may only need `config.py`: ```python # arioso/platforms/myplatform/config.py PLATFORM_CONFIG = { "name": "myplatform", "display_name": "My Platform", "website": "https://myplatform.com", "tier": "simple", "access_type": "rest_api", "auth": { "type": "bearer_token", "env_var": "MYPLATFORM_API_KEY", }, "param_map": { "prompt": {"native_name": "text", "required": True}, "duration": {"native_name": "length_seconds"}, }, "supported_affordances": ["prompt", "duration"], "on_unsupported_param": "warn", "output": { "default_format": "mp3", "sample_rate": 44100, "returns": "bytes", }, "api": { "base_url": "https://api.myplatform.com", "generate_endpoint": {"method": "post", "path": "/v1/generate"}, }, } ``` The platform is auto-discovered on the next `arioso.list_platforms()` call. ### Custom adapter (Python library) For platforms that are Python libraries rather than REST APIs, add an `adapter.py`: ```python # arioso/platforms/myplatform/adapter.py from arioso.base import Song, AudioResult class Adapter: def __init__(self, config): self.config = config def generate(self, prompt, *, duration=10, **kwargs): # Your generation logic here from some_library import generate_audio audio = generate_audio(prompt, length=duration) return Song( audio=AudioResult(audio_array=audio, sample_rate=44100, format="wav"), platform="myplatform", status="complete", ) ``` ### Manual registration Third-party packages can register platforms at runtime: ```python from arioso.registry import register_platform register_platform("custom", my_config_dict, my_adapter_instance) ``` ## Platforms Without Public APIs The following platforms were considered during the design of arioso’s unified parameter vocabulary and affordance system, but do not have public APIs (nor a reliable third-party API wrapper). They are listed here for completeness. | Platform | Website | What It Does | Affordances Considered | |----------------|------------------------------------------|--------------------------------------------------------------------------------------------------------|----------------------------------------| | **AIVA** | [aiva.ai](https://aiva.ai) | Orchestral AI composition. Desktop/web DAW with 250+ style presets, direct BPM/key/instrument control. | genre, bpm, key, instruments, duration | | **ACE Studio** | [acestudio.ai](https://acestudio.ai) | AI vocal synthesis DAW plugin. 140+ voice models for singing voice generation. | voice_id, lyrics, instruments | | **Boomy** | [boomy.com](https://boomy.com) | AI song creation with Auto Vocal and streaming platform distribution. Enterprise-only API. | prompt, voice_id, instrumental | | **Soundraw** | [soundraw.io](https://soundraw.io) | AI music generation for content creators. Enterprise B2B API only ($11/mo consumer web app). | genre, duration, energy | | **CassetteAI** | [cassetteai.com](https://cassetteai.com) | Prompt-based music generation. Web-only, no known API. | prompt, duration | | **Musicfy** | [musicfy.lol](https://musicfy.lol) | AI music generation with voice cloning and pitch shifting. Web-only, no known API. | prompt, voice_id, pitch_shift | ## Research & Background Arioso’s design is informed by extensive research into the AI music generation landscape. Two reference documents in [`misc/docs/`]() provide the full background: ### Platform comparison and API landscape [**AI Music Generation Tools: A Unified API Reference for 21 Platforms**]() maps the full union of capabilities across every tool we investigated. Highlights: - [General characteristics comparison]() — pricing, API availability, max length, sample rate, vocal support, and quality tier for 18 tools - [Documentation and integration links]() — docs URLs, OpenAPI specs, Python/JS SDKs, and MCP servers per platform - [Feature affordance matrix]() — which platforms support text prompts, negative prompts, lyrics, audio conditioning, melody conditioning, duration, BPM, key, genre tags, energy, instruments, and more - [Unified affordance mapping]() — the 40 common parameter names that arioso exposes, with native parameter names per platform - [Complete API parameter catalogs]() — full endpoint and parameter documentation for Suno, ElevenLabs, MusicGen, Lyria RealTime, Stable Audio Open, and YuE ### Prompt engineering across platforms [**Prompt Engineering for Music AI Generation: A Resource Guide**]() compiles 78 resources (papers, datasets, tools, taxonomies, and guides) covering how to write effective prompts for text-to-music systems. Key sections: - [Papers on prompt engineering techniques]() — chain-of-thought prompting, prompt tuning, user studies, and structured prompting strategies - [Model architecture and text encoders]() — how T5, CLAP, FLAN-T5, and MuLan encoders determine which prompt styles work best - [Text-audio alignment models]() — CLAP, MuLan, LAION-CLAP, and how they shape the vocabulary space - [CFG and parameter interactions]() — how guidance scale, temperature, and other parameters interact with text prompts - [Captioning datasets defining vocabulary]() — MusicCaps, LP-MusicCaps, MusicBench, and 11 other datasets that trained these models - [Vocabulary and taxonomy resources]() — AudioSet ontology, Music Ontology, Cyanite AI taxonomy - [Platform-specific prompt guides]() — official and community guides for Stable Audio, Udio, Lyria, Suno, ElevenLabs, and more Each platform also has a `_REFERENCE.md` in its directory under `arioso/platforms/` with platform-specific prompt engineering guidance, API details, and links to further reading. ## Architecture ```default arioso/ __init__.py # Facade: generate(), list_platforms() base.py # Song, AudioResult, AFFORDANCES (42 unified params) registry.py # Auto-discovery, lazy loading, manual registration translation.py # Parameter renaming & coercion (common -> native) _util.py # Auth helpers, HTTP session factory platforms/ _base_adapter.py # BaseRestAdapter (shared REST infrastructure) musicgen/ # Local inference via audiocraft/transformers stable_audio/ # Local inference via diffusers harmonai/ # Unconditional generation via Dance Diffusion riffusion/ # Spectrogram-based via diffusers elevenlabs/ # REST with OpenAPI spec via ho sunoapi/ # REST via sunoapi.org lyria2/ # Google Vertex AI REST lyria_rt/ # Google Lyria RealTime WebSocket mubert/ # Mubert REST API beatoven/ # Beatoven.ai REST API loudly/ # Loudly REST API jen/ # Jen REST API yue/ # YuE via fal.ai or local CLI stable_audio_25/ # Stable Audio 2.5 via fal.ai (audio-to-audio with strength) ace_step/ # ACE-Step via fal.ai (tags -> music, audio remix) udio/ # Udio via unofficial wrapper ``` Key design choices: - **Zero required dependencies.** The core package imports nothing outside stdlib. Platform dependencies are lazy-imported when you first call `generate()`. - **Config-driven plugins.** Each platform declares a `PLATFORM_CONFIG` dict with parameter mappings, auth scheme, endpoints, and output format. Adding a platform is mostly configuration. - **Automatic parameter translation.** The translation layer renames unified affordance names to native platform names and applies type coercions (e.g. `duration` seconds to `music_length_ms` milliseconds for ElevenLabs) for platforms served by the config-generated REST adapter. A platform with its own `adapter.py` takes unified names directly, on every path (`arioso.generate` and `arioso.services..generate` alike). - **Leverages existing libraries.** Uses [ho](https://github.com/i2mint/ho) for OpenAPI-to-Python-function generation, [i2](https://github.com/i2mint/i2) for signature manipulation and function wrapping.

This documentation as a single file: arioso.md (Markdown, for agents).

# _autosummary/arioso.base.html.md # arioso.base Core types and constants for arioso. Defines the unified output types (Song, AudioResult) and the canonical set of affordance names that all platform adapters map to. ### Classes | [`Affordance`](_autosummary/arioso.base.html.md#arioso.base.Affordance)(name, type, description[, default]) | Descriptor for a unified parameter affordance. | |---------------------------------------------------------------------------------------------------|----------------------------------------------------------| | [`AudioResult`](_autosummary/arioso.base.html.md#arioso.base.AudioResult)([audio_bytes, audio_url, ...]) | Unified audio output from any music generation platform. | | [`Song`](_autosummary/arioso.base.html.md#arioso.base.Song)([id, title, status, audio, metadata, ...]) | A generated song with its metadata and audio data. | ### *class* arioso.base.Affordance(name, type, description, default=None) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) Descriptor for a unified parameter affordance. #### name Canonical parameter name used at the facade level. #### type Expected Python type. #### description Human-readable description. #### default Default value (None means no default / required). ### *class* arioso.base.AudioResult(audio_bytes=None, audio_url='', audio_array=None, sample_rate=0, format='', duration_seconds=0.0) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) Unified audio output from any music generation platform. Exactly one of audio_bytes, audio_url, or audio_array will typically be populated by the platform adapter. Conversion between forms can be done on demand by the caller. #### audio_bytes Raw audio file bytes (MP3, WAV, etc.). #### audio_url URL to download the audio file. #### audio_array Numpy array of audio samples. #### sample_rate Sample rate in Hz (e.g. 44100, 32000). #### format Audio format string (e.g. “mp3”, “wav”, “pcm”). #### duration_seconds Duration of the audio in seconds. ### *class* arioso.base.Song(id='', title='', status='pending', audio=, metadata=, platform='') Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) A generated song with its metadata and audio data. #### id Provider-specific identifier for the song. #### title Song title (may be auto-generated by the platform). #### status Generation status: pending, generating, complete, error. #### audio The audio output. #### metadata Provider-specific metadata dict. #### platform Name of the platform that generated this song. #### *property* audio_array *: [Any](https://docs.python.org/3/library/typing.html#typing.Any) | [None](https://docs.python.org/3/builtins/constants.html#None)* Shortcut to audio.audio_array. #### *property* audio_bytes *: [bytes](https://docs.python.org/3/builtins/stdtypes.html#bytes) | [None](https://docs.python.org/3/builtins/constants.html#None)* Shortcut to audio.audio_bytes. #### *property* audio_url *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)* Shortcut to audio.audio_url. #### *property* error_message *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)* Extract error message from metadata, if any. #### *property* is_error *: [bool](https://docs.python.org/3/builtins/functions.html#bool)* Check if this Song represents an error response. #### *property* sample_rate *: [int](https://docs.python.org/3/builtins/functions.html#int)* Shortcut to audio.sample_rate. # _autosummary/arioso.html.md # arioso Arioso - Unified facade for AI music generation platforms. Usage: ```default import arioso # Generate with the default platform (musicgen) song = arioso.generate("upbeat jazz piano", duration=10) # Generate with a specific platform song = arioso.generate("epic orchestral", platform="elevenlabs", duration=30) # List available platforms arioso.list_platforms() # ['musicgen', 'sunoapi', 'elevenlabs', ...] # Get platform config arioso.get_platform_info("musicgen") # Rich platform access via services s = arioso.services.sunoapi s.generate("jazz piano", duration=30) # unified names s.native_generate("jazz", genre="jazz") # native names s.upload_file("/path/to/audio.mp3") # platform-specific # Cross-platform slices arioso.generators["sunoapi"]("jazz") arioso.generators.sunoapi("jazz") ``` ### Module Attributes | [`AUDIO_INPUT_AFFORDANCES`](_autosummary/arioso.html.md#arioso.AUDIO_INPUT_AFFORDANCES) | Affordances that carry caller-supplied *input* audio (used by [`enhance()`](_autosummary/arioso.html.md#arioso.enhance)). | |----------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------| ### Functions | [`check_status`](_autosummary/arioso.html.md#arioso.check_status)(song) | Check the current status of a pending Song and return updated Songs. | |----------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------| | [`enhance`](_autosummary/arioso.html.md#arioso.enhance)(audio[, prompt, platform, strength, as_]) | Transform existing audio into AI-enhanced audio (pipeline stage 3->4). | | [`fetch_audio`](_autosummary/arioso.html.md#arioso.fetch_audio)(song) | Download the audio bytes for a Song that has an audio_url. | | [`generate`](_autosummary/arioso.html.md#arioso.generate)(prompt, \*[, platform]) | Generate music using the specified platform. | | [`generate_many`](_autosummary/arioso.html.md#arioso.generate_many)(prompt, \*[, platform]) | Generate music, returning all results (some platforms return multiple). | | [`get_platform_info`](_autosummary/arioso.html.md#arioso.get_platform_info)(name) | Get configuration info for a platform. | | [`list_platforms`](_autosummary/arioso.html.md#arioso.list_platforms)() | Return names of all available platforms. | | [`supports_audio_input`](_autosummary/arioso.html.md#arioso.supports_audio_input)(platform) | Whether *platform* can condition on caller-supplied input audio. | ### arioso.AUDIO_INPUT_AFFORDANCES *= ('audio_input', 'melody', 'reference_audio')* Affordances that carry caller-supplied *input* audio (used by [`enhance()`](_autosummary/arioso.html.md#arioso.enhance)). Distinct from clip-extension affordances like `continue_from` (which reference a prior generation by id/URL rather than uploaded audio). ### arioso.check_status(song) Check the current status of a pending Song and return updated Songs. For platforms that use async/callback-based generation (like sunoapi), this polls the platform’s status endpoint to get the latest state, including audio URLs once generation is complete. * **Parameters:** **song** ([`Song`](_autosummary/arioso.base.html.md#arioso.base.Song)) – A Song object (typically with status=’pending’). * **Return type:** [`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[[`Song`](_autosummary/arioso.base.html.md#arioso.base.Song)] * **Returns:** List of updated Song objects with current status and audio URLs. Example: ```default songs = arioso.generate_many("reggae", platform="sunoapi", ...) # ... wait a bit ... updated = arioso.check_status(songs[0]) if updated[0].status == "complete": print(updated[0].audio_url) ``` ### arioso.enhance(audio, prompt='', , platform='stable_audio', strength=None, as_='auto', \*\*kwargs) Transform existing audio into AI-enhanced audio (pipeline stage 3->4). Progressive-disclosure sugar over [`generate()`](_autosummary/arioso.html.md#arioso.generate): routes *audio* into the platform’s audio-conditioning affordance and generates. This is the entry point for the “rendered MIDI audio -> AI-enhanced audio” step. * **Parameters:** * **audio** – The input audio to transform – a [`Song`](_autosummary/arioso.base.html.md#arioso.base.Song), [`AudioResult`](_autosummary/arioso.base.html.md#arioso.base.AudioResult), `bytes`, a file path, an `(array, sample_rate)` pair, or a NumPy waveform (normalized by `arioso._audio.to_audio_ref`). * **prompt** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str)) – Optional text guiding the transformation. * **platform** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str)) – An audio-capable platform (default `'stable_audio'`); verify with [`supports_audio_input()`](_autosummary/arioso.html.md#arioso.supports_audio_input). * **strength** ([`float`](https://docs.python.org/3/builtins/functions.html#float)) – How much the input audio influences the output (0-1), where the platform supports it. (Note: `stable_audio` via diffusers has no strength knob and will warn if one is passed.) * **as_** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str)) – Which affordance to route *audio* into – `'auto'` (default; picks `audio_input` > `melody` > `reference_audio`) or an explicit affordance name from [`AUDIO_INPUT_AFFORDANCES`](_autosummary/arioso.html.md#arioso.AUDIO_INPUT_AFFORDANCES). * **\*\*kwargs** – Further unified affordance parameters (duration, seed, …). * **Return type:** [`Song`](_autosummary/arioso.base.html.md#arioso.base.Song) * **Returns:** A [`Song`](_autosummary/arioso.base.html.md#arioso.base.Song) with the enhanced audio. Example: ```default rendered = ... # a Song from a score2audio render better = arioso.enhance(rendered, "warm analog studio band") ``` ### arioso.fetch_audio(song) Download the audio bytes for a Song that has an audio_url. * **Parameters:** **song** ([`Song`](_autosummary/arioso.base.html.md#arioso.base.Song)) – A Song with a populated audio_url (status=’complete’). * **Return type:** [`Song`](_autosummary/arioso.base.html.md#arioso.base.Song) * **Returns:** A new Song with audio_bytes populated. Example: ```default updated = arioso.check_status(song) if updated[0].status == "complete": song_with_audio = arioso.fetch_audio(updated[0]) # song_with_audio.audio_bytes is now the raw MP3 data ``` ### arioso.generate(prompt, , platform='musicgen', \*\*kwargs) Generate music using the specified platform. * **Parameters:** * **prompt** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str)) – Text description of desired music. * **platform** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str)) – Name of the generation platform (default: ‘musicgen’). * **\*\*kwargs** – Parameters using unified affordance names. See `arioso.base.AFFORDANCES` for the full list. * **Return type:** [`Song`](_autosummary/arioso.base.html.md#arioso.base.Song) * **Returns:** A Song object containing the generated audio and metadata. Example: ```default song = generate("upbeat jazz piano", platform="musicgen", duration=10) ``` ### arioso.generate_many(prompt, , platform='musicgen', \*\*kwargs) Generate music, returning all results (some platforms return multiple). Same interface as [`generate()`](_autosummary/arioso.html.md#arioso.generate) but always returns a list. * **Return type:** [`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[[`Song`](_autosummary/arioso.base.html.md#arioso.base.Song)] ### arioso.get_platform_info(name) Get configuration info for a platform. * **Parameters:** **name** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str)) – Platform identifier. * **Return type:** [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict) * **Returns:** The platform’s PLATFORM_CONFIG dict. ### arioso.list_platforms() Return names of all available platforms. * **Return type:** [`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str)] ### arioso.supports_audio_input(platform) Whether *platform* can condition on caller-supplied input audio. Returns True if the platform declares any of [`AUDIO_INPUT_AFFORDANCES`](_autosummary/arioso.html.md#arioso.AUDIO_INPUT_AFFORDANCES) (`audio_input` / `melody` / `reference_audio`) in its config’s `supported_affordances`. Example: ```default arioso.supports_audio_input("stable_audio") # True arioso.supports_audio_input("mubert") # False ``` * **Return type:** [`bool`](https://docs.python.org/3/builtins/functions.html#bool) ### Modules | [`base`](_autosummary/arioso.base.html.md#module-arioso.base) | Core types and constants for arioso. | |--------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------| | [`named_prompts`](_autosummary/arioso.named_prompts.html.md#module-arioso.named_prompts) | Named prompts: a ledger of (name, prompt_text) pairs organized by category. | | [`platforms`](_autosummary/arioso.platforms.html.md#module-arioso.platforms) | Platform packages for arioso. | | [`registry`](_autosummary/arioso.registry.html.md#module-arioso.registry) | Platform registry with auto-discovery and lazy loading. | | [`services`](_autosummary/arioso.services.html.md#arioso.services) | Lazy mapping of platform names to `ServiceHandle` objects. | | [`tools`](_autosummary/arioso.tools.html.md#module-arioso.tools) | High-level tools for common arioso workflows (submit, poll, download). | | [`translation`](_autosummary/arioso.translation.html.md#module-arioso.translation) | Parameter translation layer. | # _autosummary/arioso.named_prompts.html.md # arioso.named_prompts Named prompts: a ledger of (name, prompt_text) pairs organized by category. Provides a system for looking up sonic descriptions by name (artist, mood, genre, instrument, etc.) to help users craft prompts for AI music generation without using restricted names. The system has two layers: - **Starter data**: ships with arioso in `arioso/data/named_prompts/*.yaml` - **User data**: stored in `~/.local/share/arioso/named_prompts/*.yaml` User data overlays starter data, so users can extend or override entries. Usage: ```default >>> from arioso.named_prompts import named_prompts, search >>> named_prompts.artists['billie_eilish'] # attribute access by category '...' >>> named_prompts['artists', 'billie_eilish'] # flat key access '...' >>> results = search('jazz') # search across all categories ``` ### Functions | [`add_prompt`](_autosummary/arioso.named_prompts.html.md#arioso.named_prompts.add_prompt)(category, name, prompt_text, \*[, ...]) | Add or update a prompt in the user's data. | |-------------------------------------------------------------------------------------------------------|----------------------------------------------------------| | [`get_named_prompts`](_autosummary/arioso.named_prompts.html.md#arioso.named_prompts.get_named_prompts)() | Return a module-level singleton `NamedPrompts` instance. | | [`remove_prompt`](_autosummary/arioso.named_prompts.html.md#arioso.named_prompts.remove_prompt)(category, name) | Remove a prompt from the user's data. | | [`search`](_autosummary/arioso.named_prompts.html.md#arioso.named_prompts.search)(query, \*[, categories, ...]) | Search for prompts matching a query string. | ### Classes | [`NamedPrompts`](_autosummary/arioso.named_prompts.html.md#arioso.named_prompts.NamedPrompts)(\*[, include_user_data]) | Two-level mapping of `(category, name) -> prompt_text`. | |------------------------------------------------------------------------------------------|-----------------------------------------------------------| ### *class* arioso.named_prompts.NamedPrompts(, include_user_data=True) Bases: [`Mapping`](https://docs.python.org/3/library/typing.html#typing.Mapping) Two-level mapping of `(category, name) -> prompt_text`. Supports both hierarchical and flat access: ```default np = NamedPrompts() np.artists['billie_eilish'] # attribute access to a category np['artists']['billie_eilish'] # dict-style np['artists', 'billie_eilish'] # flat tuple key ``` Categories are auto-discovered from YAML files in the starter and user dirs. * **Parameters:** **include_user_data** ([`bool`](https://docs.python.org/3/builtins/functions.html#bool)) – Whether to layer user data on top of starter data. Defaults to `True`. #### *property* categories *: [Tuple](https://docs.python.org/3/library/typing.html#typing.Tuple)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), ...]* Return all available category names. #### flat() Return a flat dict of `{(category, name): prompt_text}`. * **Return type:** [`Dict`](https://docs.python.org/3/library/typing.html#typing.Dict)[[`Tuple`](https://docs.python.org/3/library/typing.html#typing.Tuple)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`str`](https://docs.python.org/3/builtins/stdtypes.html#str)], [`str`](https://docs.python.org/3/builtins/stdtypes.html#str)] #### flat_names(, warn_collisions=True) Return a flat dict of `{name: prompt_text}`, ignoring categories. If the same name appears in multiple categories, the last one wins and a warning is issued (unless `warn_collisions=False`). * **Return type:** [`Dict`](https://docs.python.org/3/library/typing.html#typing.Dict)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`str`](https://docs.python.org/3/builtins/stdtypes.html#str)] ### arioso.named_prompts.add_prompt(category, name, prompt_text, , confirm_override=True) Add or update a prompt in the user’s data. If the name already exists in either user or starter data and `confirm_override` is True, a confirmation prompt is printed on the first collision. * **Parameters:** * **category** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str)) – The category to add to (e.g. ‘artists’, ‘moods’). * **name** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str)) – The identifier for this prompt. * **prompt_text** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str)) – The sonic description / prompt text. * **confirm_override** ([`bool`](https://docs.python.org/3/builtins/functions.html#bool)) – If True, warn when overriding an existing entry. * **Return type:** [`None`](https://docs.python.org/3/builtins/constants.html#None) ### arioso.named_prompts.get_named_prompts() Return a module-level singleton `NamedPrompts` instance. * **Return type:** [`NamedPrompts`](_autosummary/arioso.named_prompts.html.md#arioso.named_prompts.NamedPrompts) ### arioso.named_prompts.remove_prompt(category, name) Remove a prompt from the user’s data. This only removes from user data. Starter data entries cannot be removed (but can be overridden via `add_prompt`). * **Return type:** [`None`](https://docs.python.org/3/builtins/constants.html#None) ### arioso.named_prompts.search(query, , categories=None, search_prompts=True, search_names=True) Search for prompts matching a query string. * **Parameters:** * **query** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str)) – Case-insensitive substring to search for. * **categories** ([`Optional`](https://docs.python.org/3/library/typing.html#typing.Optional)[[`Tuple`](https://docs.python.org/3/library/typing.html#typing.Tuple)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`...`](https://docs.python.org/3/builtins/constants.html#Ellipsis)]]) – If given, restrict search to these categories. * **search_prompts** ([`bool`](https://docs.python.org/3/builtins/functions.html#bool)) – Whether to search in prompt text. * **search_names** ([`bool`](https://docs.python.org/3/builtins/functions.html#bool)) – Whether to search in entry names. * **Return type:** [`Dict`](https://docs.python.org/3/library/typing.html#typing.Dict)[[`Tuple`](https://docs.python.org/3/library/typing.html#typing.Tuple)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`str`](https://docs.python.org/3/builtins/stdtypes.html#str)], [`str`](https://docs.python.org/3/builtins/stdtypes.html#str)] * **Returns:** Dict of `{(category, name): prompt_text}` for all matches. # _autosummary/arioso.platforms.ace_step.adapter.html.md # arioso.platforms.ace_step.adapter ACE-Step adapter (fal.ai): text-to-music and audio-to-audio remix. ACE-Step is steered by comma-separated style *tags*, not a sentence, so the unified `prompt` (or `genre`) becomes `tags`. Its audio-to-audio endpoint “remixes” an input toward new tags; it also needs `original_tags` describing the input, which default to the new tags when not given. ### Classes | [`Adapter`](_autosummary/arioso.platforms.ace_step.adapter.html.md#arioso.platforms.ace_step.adapter.Adapter)(config) | fal.ai ACE-Step adapter. | |--------------------------------------------------------------------|----------------------------| ### *class* arioso.platforms.ace_step.adapter.Adapter(config) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) fal.ai ACE-Step adapter. #### generate(prompt='', , genre='', lyrics='', instrumental=False, duration=60.0, num_steps=27, guidance=15.0, seed=None, audio_input=None, original_tags='', original_lyrics='', edit_mode='remix', fetch=True, \*\*kwargs) Generate music from tags, or remix `audio_input` toward them. * **Parameters:** * **prompt** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str)) – Style tags (comma-separated works best). `genre` wins when both are given. * **genre** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str)) – Style tags; an alias of `prompt` for this platform. * **lyrics** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str)) – Lyrics to sing. Empty or `instrumental=True` sends `[inst]`, so a remix of a song with vocals comes out instrumental unless you pass its lyrics (or new ones). * **instrumental** ([`bool`](https://docs.python.org/3/builtins/functions.html#bool)) – Force an instrumental (discards `lyrics`). * **duration** ([`float`](https://docs.python.org/3/builtins/functions.html#float)) – Seconds (text-to-music only; a remix keeps the input’s length). * **num_steps** ([`int`](https://docs.python.org/3/builtins/functions.html#int)) – `number_of_steps` (default 27). * **guidance** ([`float`](https://docs.python.org/3/builtins/functions.html#float)) – `guidance_scale` (default 15). * **seed** ([`int`](https://docs.python.org/3/builtins/functions.html#int)) – Random seed. * **audio_input** – Audio to remix (path, bytes, Song, URL, …). When given, the audio-to-audio endpoint is used. * **original_tags** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str)) – Tags describing `audio_input` (defaults to the new tags). * **original_lyrics** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str)) – Lyrics of `audio_input`, if any. * **edit_mode** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str)) – `"remix"` (default) or `"lyrics"`. * **fetch** ([`bool`](https://docs.python.org/3/builtins/functions.html#bool)) – Download the result so `audio_bytes` is populated. * **\*\*kwargs** – Native fal arguments in `_NATIVE_EXTRAS` (`scheduler`, `guidance_type`, `tag_guidance_scale`, …) are passed through; anything else is ignored. * **Return type:** [`Song`](_autosummary/arioso.base.html.md#arioso.base.Song) * **Returns:** A completed Song. # _autosummary/arioso.platforms.ace_step.config.html.md # arioso.platforms.ace_step.config ACE-Step platform configuration (fal.ai hosted). Live docs (verified 2026-10-03): [https://fal.ai/models/fal-ai/ace-step/api](https://fal.ai/models/fal-ai/ace-step/api) and [https://fal.ai/models/fal-ai/ace-step/audio-to-audio/api](https://fal.ai/models/fal-ai/ace-step/audio-to-audio/api) # _autosummary/arioso.platforms.ace_step.html.md # arioso.platforms.ace_step ACE-Step (hosted on fal.ai) platform for arioso. ### Modules | [`adapter`](_autosummary/arioso.platforms.ace_step.adapter.html.md#module-arioso.platforms.ace_step.adapter) | ACE-Step adapter (fal.ai): text-to-music and audio-to-audio remix. | |-----------------------------------------------------------------------------------------------------|----------------------------------------------------------------------| | [`config`](_autosummary/arioso.platforms.ace_step.config.html.md#module-arioso.platforms.ace_step.config) | ACE-Step platform configuration (fal.ai hosted). | # _autosummary/arioso.platforms.beatoven.adapter.html.md # arioso.platforms.beatoven.adapter Beatoven.ai adapter via REST API. ### Classes | [`Adapter`](_autosummary/arioso.platforms.beatoven.adapter.html.md#arioso.platforms.beatoven.adapter.Adapter)(config) | Adapter for Beatoven.ai music generation. | |--------------------------------------------------------------------|---------------------------------------------| ### *class* arioso.platforms.beatoven.adapter.Adapter(config) Bases: `BaseRestAdapter` Adapter for Beatoven.ai music generation. Beatoven uses a three-step flow: 1. POST /tracks to create a track and get a track_id. 2. Poll GET /tracks/{track_id} until status is ‘composed’. 3. GET /tracks/{track_id}/audio to retrieve the download URL. #### generate(prompt, , duration=30, negative_prompt='', seed=None, guidance=16, num_steps=100, looping=False, wait_for_completion=True, poll_interval=5.0, timeout=300.0, \*\*kwargs) Generate music via Beatoven.ai. * **Parameters:** * **prompt** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str)) – Text description of desired music. * **duration** ([`float`](https://docs.python.org/3/builtins/functions.html#float)) – Track duration in seconds (5-150). * **negative_prompt** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str)) – Elements to avoid in generation. * **seed** ([`int`](https://docs.python.org/3/builtins/functions.html#int) | [`None`](https://docs.python.org/3/builtins/constants.html#None)) – Random seed for reproducibility. * **guidance** ([`float`](https://docs.python.org/3/builtins/functions.html#float)) – Creativity/guidance scale (default 16). * **num_steps** ([`int`](https://docs.python.org/3/builtins/functions.html#int)) – Refinement steps (default 100). * **looping** ([`bool`](https://docs.python.org/3/builtins/functions.html#bool)) – Whether to generate loopable audio. * **wait_for_completion** ([`bool`](https://docs.python.org/3/builtins/functions.html#bool)) – If True, poll until audio is ready. * **poll_interval** ([`float`](https://docs.python.org/3/builtins/functions.html#float)) – Seconds between status checks. * **timeout** ([`float`](https://docs.python.org/3/builtins/functions.html#float)) – Max seconds to wait for completion. * **Return type:** [`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[[`Song`](_autosummary/arioso.base.html.md#arioso.base.Song)] * **Returns:** List containing a single Song object. #### get_audio_url(track_id) Retrieve the audio download URL for a completed track. * **Parameters:** **track_id** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str)) – The track ID of a composed track. * **Return type:** [`str`](https://docs.python.org/3/builtins/stdtypes.html#str) * **Returns:** The audio download URL. #### get_status(track_id) Check the generation status of a track. * **Parameters:** **track_id** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str)) – The track ID returned from generate(). * **Return type:** [`str`](https://docs.python.org/3/builtins/stdtypes.html#str) * **Returns:** Status string from the API (e.g. ‘composing’, ‘composed’). # _autosummary/arioso.platforms.beatoven.config.html.md # arioso.platforms.beatoven.config Beatoven.ai platform configuration. # _autosummary/arioso.platforms.beatoven.html.md # arioso.platforms.beatoven Beatoven.ai platform for arioso. ### Modules | [`adapter`](_autosummary/arioso.platforms.beatoven.adapter.html.md#module-arioso.platforms.beatoven.adapter) | Beatoven.ai adapter via REST API. | |-----------------------------------------------------------------------------------------------------|-------------------------------------| | [`config`](_autosummary/arioso.platforms.beatoven.config.html.md#module-arioso.platforms.beatoven.config) | Beatoven.ai platform configuration. | # _autosummary/arioso.platforms.elevenlabs.adapter.html.md # arioso.platforms.elevenlabs.adapter ElevenLabs Music adapter. Uses `ho.route_to_func` to auto-generate the raw callable from the ElevenLabs OpenAPI spec, then handles parameter translation for complex fields like `composition_plan`. ### Classes | [`Adapter`](_autosummary/arioso.platforms.elevenlabs.adapter.html.md#arioso.platforms.elevenlabs.adapter.Adapter)(config) | ElevenLabs Music adapter with OpenAPI-based function generation. | |--------------------------------------------------------------------|--------------------------------------------------------------------| ### *class* arioso.platforms.elevenlabs.adapter.Adapter(config) Bases: `BaseRestAdapter` ElevenLabs Music adapter with OpenAPI-based function generation. #### generate(prompt, , duration=30.0, instrumental=False, model='music_v1', output_format='mp3_44100_128', lyrics='', title='', structure=None, watermark=False, seed=None, \*\*kwargs) Generate music using the ElevenLabs Music API. * **Parameters:** * **prompt** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str)) – Text description of desired music. * **duration** ([`float`](https://docs.python.org/3/builtins/functions.html#float)) – Length in seconds (3-600). * **instrumental** ([`bool`](https://docs.python.org/3/builtins/functions.html#bool)) – If True, generate without vocals. * **model** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str)) – Model ID. * **output_format** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str)) – Output format string (e.g. ‘mp3_44100_128’). * **lyrics** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str)) – Custom lyrics text. * **title** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str)) – Song title. * **structure** ([`list`](https://docs.python.org/3/builtins/stdtypes.html#list)) – Song section structure (list of dicts). * **watermark** ([`bool`](https://docs.python.org/3/builtins/functions.html#bool)) – Apply C2PA content watermark. * **seed** ([`int`](https://docs.python.org/3/builtins/functions.html#int)) – Random seed (streaming endpoint only). * **Return type:** [`Song`](_autosummary/arioso.base.html.md#arioso.base.Song) * **Returns:** A Song with audio_bytes populated. # _autosummary/arioso.platforms.elevenlabs.config.html.md # arioso.platforms.elevenlabs.config ElevenLabs Music platform configuration. # _autosummary/arioso.platforms.elevenlabs.html.md # arioso.platforms.elevenlabs ElevenLabs Music platform for arioso. ### Modules | [`adapter`](_autosummary/arioso.platforms.elevenlabs.adapter.html.md#module-arioso.platforms.elevenlabs.adapter) | ElevenLabs Music adapter. | |-------------------------------------------------------------------------------------------------------|------------------------------------------| | [`config`](_autosummary/arioso.platforms.elevenlabs.config.html.md#module-arioso.platforms.elevenlabs.config) | ElevenLabs Music platform configuration. | # _autosummary/arioso.platforms.harmonai.adapter.html.md # arioso.platforms.harmonai.adapter Harmonai (Dance Diffusion) adapter using diffusers. ### Classes | [`Adapter`](_autosummary/arioso.platforms.harmonai.adapter.html.md#arioso.platforms.harmonai.adapter.Adapter)(config) | Dance Diffusion adapter with lazy model loading. | |--------------------------------------------------------------------|----------------------------------------------------| ### *class* arioso.platforms.harmonai.adapter.Adapter(config) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) Dance Diffusion adapter with lazy model loading. Uses the `diffusers` library to run unconditional audio generation via the Dance Diffusion pipeline. #### generate(prompt='', , num_steps=100, seed=None, batch_size=1, \*\*kwargs) Generate audio unconditionally. * **Parameters:** * **prompt** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str)) – Ignored (unconditional model). A warning is emitted if a non-empty prompt is provided. * **num_steps** ([`int`](https://docs.python.org/3/builtins/functions.html#int)) – Number of diffusion inference steps. * **seed** ([`int`](https://docs.python.org/3/builtins/functions.html#int)) – Random seed for reproducibility. * **batch_size** ([`int`](https://docs.python.org/3/builtins/functions.html#int)) – Number of audio samples to generate. * **Return type:** [`Song`](_autosummary/arioso.base.html.md#arioso.base.Song) * **Returns:** A Song with audio_array populated. # _autosummary/arioso.platforms.harmonai.config.html.md # arioso.platforms.harmonai.config Harmonai (Dance Diffusion) platform configuration. # _autosummary/arioso.platforms.harmonai.html.md # arioso.platforms.harmonai Harmonai (Dance Diffusion) platform for arioso. ### Modules | [`adapter`](_autosummary/arioso.platforms.harmonai.adapter.html.md#module-arioso.platforms.harmonai.adapter) | Harmonai (Dance Diffusion) adapter using diffusers. | |-----------------------------------------------------------------------------------------------------|-------------------------------------------------------| | [`config`](_autosummary/arioso.platforms.harmonai.config.html.md#module-arioso.platforms.harmonai.config) | Harmonai (Dance Diffusion) platform configuration. | # _autosummary/arioso.platforms.html.md # arioso.platforms Platform packages for arioso. Each subdirectory is a platform plugin containing at minimum a `config.py` with a `PLATFORM_CONFIG` dict. Platforms are auto-discovered by [`arioso.registry.discover_platforms()`](_autosummary/arioso.registry.html.md#arioso.registry.discover_platforms). ### Modules | [`ace_step`](_autosummary/arioso.platforms.ace_step.html.md#module-arioso.platforms.ace_step) | ACE-Step (hosted on fal.ai) platform for arioso. | |----------------------------------------------------------------------------------------------------------|----------------------------------------------------------| | [`beatoven`](_autosummary/arioso.platforms.beatoven.html.md#module-arioso.platforms.beatoven) | Beatoven.ai platform for arioso. | | [`elevenlabs`](_autosummary/arioso.platforms.elevenlabs.html.md#module-arioso.platforms.elevenlabs) | ElevenLabs Music platform for arioso. | | [`harmonai`](_autosummary/arioso.platforms.harmonai.html.md#module-arioso.platforms.harmonai) | Harmonai (Dance Diffusion) platform for arioso. | | [`jen`](_autosummary/arioso.platforms.jen.html.md#module-arioso.platforms.jen) | Jen platform for arioso. | | [`loudly`](_autosummary/arioso.platforms.loudly.html.md#module-arioso.platforms.loudly) | Loudly platform for arioso. | | [`lyria2`](_autosummary/arioso.platforms.lyria2.html.md#module-arioso.platforms.lyria2) | Google Lyria 2 platform for arioso. | | [`lyria_rt`](_autosummary/arioso.platforms.lyria_rt.html.md#module-arioso.platforms.lyria_rt) | Google Lyria RealTime platform for arioso. | | [`mubert`](_autosummary/arioso.platforms.mubert.html.md#module-arioso.platforms.mubert) | Mubert platform for arioso. | | [`musicgen`](_autosummary/arioso.platforms.musicgen.html.md#module-arioso.platforms.musicgen) | MusicGen platform for arioso. | | [`riffusion`](_autosummary/arioso.platforms.riffusion.html.md#module-arioso.platforms.riffusion) | Riffusion platform for arioso. | | [`stable_audio`](_autosummary/arioso.platforms.stable_audio.html.md#module-arioso.platforms.stable_audio) | Stable Audio Open platform for arioso. | | [`stable_audio_25`](_autosummary/arioso.platforms.stable_audio_25.html.md#module-arioso.platforms.stable_audio_25) | Stable Audio 2.5 (hosted on fal.ai) platform for arioso. | | [`sunoapi`](_autosummary/arioso.platforms.sunoapi.html.md#module-arioso.platforms.sunoapi) | Suno platform (via sunoapi.org) for arioso. | | [`udio`](_autosummary/arioso.platforms.udio.html.md#module-arioso.platforms.udio) | Udio platform (via UdioWrapper) for arioso. | | [`yue`](_autosummary/arioso.platforms.yue.html.md#module-arioso.platforms.yue) | YuE platform for arioso. | # _autosummary/arioso.platforms.jen.adapter.html.md # arioso.platforms.jen.adapter Jen adapter via REST API. ### Classes | [`Adapter`](_autosummary/arioso.platforms.jen.adapter.html.md#arioso.platforms.jen.adapter.Adapter)(config) | Adapter for Jen music generation. | |--------------------------------------------------------------------|-------------------------------------| ### *class* arioso.platforms.jen.adapter.Adapter(config) Bases: `BaseRestAdapter` Adapter for Jen music generation. #### generate(prompt, , duration=30, output_format='mp3', continue_from='', \*\*kwargs) Generate music via Jen. * **Parameters:** * **prompt** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str)) – Text description of desired music. * **duration** ([`float`](https://docs.python.org/3/builtins/functions.html#float)) – Track duration in seconds. * **output_format** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str)) – Output format (‘mp3’ or ‘wav’). * **continue_from** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str)) – Track ID or URL to extend from. * **Return type:** [`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[[`Song`](_autosummary/arioso.base.html.md#arioso.base.Song)] * **Returns:** List containing a single Song object. # _autosummary/arioso.platforms.jen.config.html.md # arioso.platforms.jen.config Jen platform configuration. # _autosummary/arioso.platforms.jen.html.md # arioso.platforms.jen Jen platform for arioso. ### Modules | [`adapter`](_autosummary/arioso.platforms.jen.adapter.html.md#module-arioso.platforms.jen.adapter) | Jen adapter via REST API. | |------------------------------------------------------------------------------------------------|-----------------------------| | [`config`](_autosummary/arioso.platforms.jen.config.html.md#module-arioso.platforms.jen.config) | Jen platform configuration. | # _autosummary/arioso.platforms.loudly.adapter.html.md # arioso.platforms.loudly.adapter Loudly adapter via REST API. ### Classes | [`Adapter`](_autosummary/arioso.platforms.loudly.adapter.html.md#arioso.platforms.loudly.adapter.Adapter)(config) | Adapter for Loudly music generation. | |--------------------------------------------------------------------|----------------------------------------| ### *class* arioso.platforms.loudly.adapter.Adapter(config) Bases: `BaseRestAdapter` Adapter for Loudly music generation. Loudly may return the audio URL directly or require polling, depending on the generation complexity. #### generate(prompt, , duration=30, genre='', bpm=None, key='', energy=None, instruments=None, structure=None, wait_for_completion=True, poll_interval=5.0, timeout=300.0, \*\*kwargs) Generate music via Loudly. * **Parameters:** * **prompt** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str)) – Text description of desired music. * **duration** ([`float`](https://docs.python.org/3/builtins/functions.html#float)) – Track duration in seconds. * **genre** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str)) – Genre tag (50+ options available). * **bpm** ([`int`](https://docs.python.org/3/builtins/functions.html#int) | [`None`](https://docs.python.org/3/builtins/constants.html#None)) – Tempo in beats per minute. * **key** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str)) – Musical key (e.g. ‘C major’). * **energy** ([`float`](https://docs.python.org/3/builtins/functions.html#float) | [`None`](https://docs.python.org/3/builtins/constants.html#None)) – Energy level (0-1). * **instruments** ([`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str)] | [`None`](https://docs.python.org/3/builtins/constants.html#None)) – List of instruments (up to 7). * **structure** ([`list`](https://docs.python.org/3/builtins/stdtypes.html#list) | [`None`](https://docs.python.org/3/builtins/constants.html#None)) – Song section structure. * **wait_for_completion** ([`bool`](https://docs.python.org/3/builtins/functions.html#bool)) – If True, poll until audio is ready. * **poll_interval** ([`float`](https://docs.python.org/3/builtins/functions.html#float)) – Seconds between status checks. * **timeout** ([`float`](https://docs.python.org/3/builtins/functions.html#float)) – Max seconds to wait for completion. * **Return type:** [`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[[`Song`](_autosummary/arioso.base.html.md#arioso.base.Song)] * **Returns:** List containing a single Song object. # _autosummary/arioso.platforms.loudly.config.html.md # arioso.platforms.loudly.config Loudly platform configuration. # _autosummary/arioso.platforms.loudly.html.md # arioso.platforms.loudly Loudly platform for arioso. ### Modules | [`adapter`](_autosummary/arioso.platforms.loudly.adapter.html.md#module-arioso.platforms.loudly.adapter) | Loudly adapter via REST API. | |---------------------------------------------------------------------------------------------------|--------------------------------| | [`config`](_autosummary/arioso.platforms.loudly.config.html.md#module-arioso.platforms.loudly.config) | Loudly platform configuration. | # _autosummary/arioso.platforms.lyria2.adapter.html.md # arioso.platforms.lyria2.adapter Google Lyria 2 adapter. Uses the `google-cloud-aiplatform` SDK when available, falling back to raw REST calls against the Vertex AI prediction endpoint. ### Classes | [`Adapter`](_autosummary/arioso.platforms.lyria2.adapter.html.md#arioso.platforms.lyria2.adapter.Adapter)(config) | Google Lyria 2 adapter with SDK-first, REST-fallback strategy. | |--------------------------------------------------------------------|------------------------------------------------------------------| ### *class* arioso.platforms.lyria2.adapter.Adapter(config) Bases: `BaseRestAdapter` Google Lyria 2 adapter with SDK-first, REST-fallback strategy. #### generate(prompt, , negative_prompt='', seed=None, model='lyria-002', batch_size=1, \*\*kwargs) Generate music using Google Lyria 2. * **Parameters:** * **prompt** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str)) – Text description of desired music. * **negative_prompt** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str)) – Elements to avoid in the generation. * **seed** ([`int`](https://docs.python.org/3/builtins/functions.html#int)) – Random seed for reproducibility. * **model** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str)) – Model version identifier. * **batch_size** ([`int`](https://docs.python.org/3/builtins/functions.html#int)) – Number of samples to generate. * **Return type:** [`Song`](_autosummary/arioso.base.html.md#arioso.base.Song) * **Returns:** A Song with WAV audio bytes (fixed 30 s duration at 48 kHz). # _autosummary/arioso.platforms.lyria2.config.html.md # arioso.platforms.lyria2.config Google Lyria 2 platform configuration. # _autosummary/arioso.platforms.lyria2.html.md # arioso.platforms.lyria2 Google Lyria 2 platform for arioso. ### Modules | [`adapter`](_autosummary/arioso.platforms.lyria2.adapter.html.md#module-arioso.platforms.lyria2.adapter) | Google Lyria 2 adapter. | |---------------------------------------------------------------------------------------------------|----------------------------------------| | [`config`](_autosummary/arioso.platforms.lyria2.config.html.md#module-arioso.platforms.lyria2.config) | Google Lyria 2 platform configuration. | # _autosummary/arioso.platforms.lyria_rt.adapter.html.md # arioso.platforms.lyria_rt.adapter Google Lyria RealTime adapter using the google-genai SDK. ### Classes | [`Adapter`](_autosummary/arioso.platforms.lyria_rt.adapter.html.md#arioso.platforms.lyria_rt.adapter.Adapter)(config) | Lyria RealTime adapter using streaming music sessions. | |--------------------------------------------------------------------|----------------------------------------------------------| ### *class* arioso.platforms.lyria_rt.adapter.Adapter(config) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) Lyria RealTime adapter using streaming music sessions. Creates a live music session via the `google-genai` SDK, sends a prompt, collects PCM audio chunks for a configurable duration, and returns them as a single `Song`. #### generate(prompt, , duration=10.0, bpm=None, key=None, energy=None, brightness=None, guidance=4.0, temperature=1.1, top_k=40, seed=None, prompt_weight=None, \*\*kwargs) Generate music using a Lyria RealTime streaming session. * **Parameters:** * **prompt** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str)) – Text description of desired music. * **duration** ([`float`](https://docs.python.org/3/builtins/functions.html#float)) – Seconds of audio to collect from the stream. * **bpm** ([`int`](https://docs.python.org/3/builtins/functions.html#int)) – Beats per minute (60-200). * **key** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str)) – Musical scale (e.g. `"C_MAJOR"`). * **energy** ([`float`](https://docs.python.org/3/builtins/functions.html#float)) – Density / energy level (0-1). * **brightness** ([`float`](https://docs.python.org/3/builtins/functions.html#float)) – Spectral brightness (0-1). * **guidance** ([`float`](https://docs.python.org/3/builtins/functions.html#float)) – Guidance strength (0-6). * **temperature** ([`float`](https://docs.python.org/3/builtins/functions.html#float)) – Sampling temperature (0-3). * **top_k** ([`int`](https://docs.python.org/3/builtins/functions.html#int)) – Top-k sampling (1-1000). * **seed** ([`int`](https://docs.python.org/3/builtins/functions.html#int)) – Random seed for reproducibility (0-2.1B). * **prompt_weight** ([`float`](https://docs.python.org/3/builtins/functions.html#float)) – Weight applied to the WeightedPrompt. * **Return type:** [`Song`](_autosummary/arioso.base.html.md#arioso.base.Song) * **Returns:** A Song with PCM audio bytes at 48 kHz. # _autosummary/arioso.platforms.lyria_rt.config.html.md # arioso.platforms.lyria_rt.config Google Lyria RealTime platform configuration. # _autosummary/arioso.platforms.lyria_rt.html.md # arioso.platforms.lyria_rt Google Lyria RealTime platform for arioso. ### Modules | [`adapter`](_autosummary/arioso.platforms.lyria_rt.adapter.html.md#module-arioso.platforms.lyria_rt.adapter) | Google Lyria RealTime adapter using the google-genai SDK. | |-----------------------------------------------------------------------------------------------------|-------------------------------------------------------------| | [`config`](_autosummary/arioso.platforms.lyria_rt.config.html.md#module-arioso.platforms.lyria_rt.config) | Google Lyria RealTime platform configuration. | # _autosummary/arioso.platforms.mubert.adapter.html.md # arioso.platforms.mubert.adapter Mubert adapter via REST API. ### Classes | [`Adapter`](_autosummary/arioso.platforms.mubert.adapter.html.md#arioso.platforms.mubert.adapter.Adapter)(config) | Adapter for Mubert music generation. | |--------------------------------------------------------------------|----------------------------------------| ### *class* arioso.platforms.mubert.adapter.Adapter(config) Bases: `BaseRestAdapter` Adapter for Mubert music generation. Mubert uses a two-step flow: POST to /RecordTrackTTM to start a task, then poll until the download_link becomes available. #### generate(prompt, , duration=30, output_format='mp3', bitrate=320, energy=None, wait_for_completion=True, poll_interval=5.0, timeout=300.0, \*\*kwargs) Generate music via Mubert. * **Parameters:** * **prompt** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str)) – Text description of desired music. * **duration** ([`float`](https://docs.python.org/3/builtins/functions.html#float)) – Track duration in seconds (15-1500). * **output_format** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str)) – Output format (‘mp3’ or ‘wav’). * **bitrate** ([`int`](https://docs.python.org/3/builtins/functions.html#int)) – Audio bitrate (128 or 320). * **energy** ([`float`](https://docs.python.org/3/builtins/functions.html#float) | [`None`](https://docs.python.org/3/builtins/constants.html#None)) – Energy level 0-1 (coerced to low/medium/high). * **wait_for_completion** ([`bool`](https://docs.python.org/3/builtins/functions.html#bool)) – If True, poll until audio is ready. * **poll_interval** ([`float`](https://docs.python.org/3/builtins/functions.html#float)) – Seconds between status checks. * **timeout** ([`float`](https://docs.python.org/3/builtins/functions.html#float)) – Max seconds to wait for completion. * **Return type:** [`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[[`Song`](_autosummary/arioso.base.html.md#arioso.base.Song)] * **Returns:** List containing a single Song object. # _autosummary/arioso.platforms.mubert.config.html.md # arioso.platforms.mubert.config Mubert platform configuration. # _autosummary/arioso.platforms.mubert.html.md # arioso.platforms.mubert Mubert platform for arioso. ### Modules | [`adapter`](_autosummary/arioso.platforms.mubert.adapter.html.md#module-arioso.platforms.mubert.adapter) | Mubert adapter via REST API. | |---------------------------------------------------------------------------------------------------|--------------------------------| | [`config`](_autosummary/arioso.platforms.mubert.config.html.md#module-arioso.platforms.mubert.config) | Mubert platform configuration. | # _autosummary/arioso.platforms.musicgen.adapter.html.md # arioso.platforms.musicgen.adapter MusicGen adapter using audiocraft (preferred) or transformers. Supports text-to-music generation and, via `facebook/musicgen-melody`, melody-conditioned generation (the `melody` affordance / `arioso.enhance` stage): the output follows the pitch contour of an input audio while taking its style from the text prompt. ### Classes | [`Adapter`](_autosummary/arioso.platforms.musicgen.adapter.html.md#arioso.platforms.musicgen.adapter.Adapter)(config) | MusicGen adapter with lazy model loading. | |--------------------------------------------------------------------|---------------------------------------------| ### *class* arioso.platforms.musicgen.adapter.Adapter(config) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) MusicGen adapter with lazy model loading. Tries `audiocraft` first; if unavailable, falls back to the HuggingFace `transformers` pipeline. #### generate(prompt, , duration=8.0, temperature=1.0, top_k=250, top_p=0.0, guidance=3.0, model='facebook/musicgen-small', melody=None, \*\*kwargs) Generate music from a text prompt, optionally following a melody. * **Parameters:** * **prompt** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str)) – Text description of desired music. * **duration** ([`float`](https://docs.python.org/3/builtins/functions.html#float)) – Length in seconds. * **temperature** ([`float`](https://docs.python.org/3/builtins/functions.html#float)) – Sampling randomness. * **top_k** ([`int`](https://docs.python.org/3/builtins/functions.html#int)) – Top-k sampling parameter. * **top_p** ([`float`](https://docs.python.org/3/builtins/functions.html#float)) – Top-p nucleus sampling. * **guidance** ([`float`](https://docs.python.org/3/builtins/functions.html#float)) – Classifier-free guidance scale. * **model** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str)) – Model variant name (e.g. ‘facebook/musicgen-small’). When a `melody` is supplied and `model` isn’t already a melody variant, it is switched to `facebook/musicgen-melody`. * **melody** – Optional input audio whose pitch contour the output follows (a Song/AudioResult/bytes/path/(array, sample_rate)/waveform). This is the `arioso.enhance` path for musicgen. * **Return type:** [`Song`](_autosummary/arioso.base.html.md#arioso.base.Song) * **Returns:** A Song with audio_array populated. # _autosummary/arioso.platforms.musicgen.config.html.md # arioso.platforms.musicgen.config MusicGen platform configuration. # _autosummary/arioso.platforms.musicgen.html.md # arioso.platforms.musicgen MusicGen platform for arioso. ### Modules | [`adapter`](_autosummary/arioso.platforms.musicgen.adapter.html.md#module-arioso.platforms.musicgen.adapter) | MusicGen adapter using audiocraft (preferred) or transformers. | |-----------------------------------------------------------------------------------------------------|------------------------------------------------------------------| | [`config`](_autosummary/arioso.platforms.musicgen.config.html.md#module-arioso.platforms.musicgen.config) | MusicGen platform configuration. | # _autosummary/arioso.platforms.riffusion.adapter.html.md # arioso.platforms.riffusion.adapter Riffusion adapter using the riffusion library or diffusers fallback. ### Classes | [`Adapter`](_autosummary/arioso.platforms.riffusion.adapter.html.md#arioso.platforms.riffusion.adapter.Adapter)(config) | Riffusion adapter with dual backend support. | |--------------------------------------------------------------------|------------------------------------------------| ### *class* arioso.platforms.riffusion.adapter.Adapter(config) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) Riffusion adapter with dual backend support. Tries the `riffusion` library first for full spectrogram-to-audio support. Falls back to the `diffusers` StableDiffusion pipeline which generates a spectrogram image and converts it to audio via inverse STFT. #### generate(prompt, , negative_prompt='', seed=None, guidance=7.0, num_steps=50, audio_input_strength=0.75, \*\*kwargs) Generate audio from a text prompt via spectrogram synthesis. * **Parameters:** * **prompt** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str)) – Text description of desired music. * **negative_prompt** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str)) – Elements to avoid in generation. * **seed** ([`int`](https://docs.python.org/3/builtins/functions.html#int)) – Random seed for reproducibility. * **guidance** ([`float`](https://docs.python.org/3/builtins/functions.html#float)) – Classifier-free guidance scale. * **num_steps** ([`int`](https://docs.python.org/3/builtins/functions.html#int)) – Number of diffusion inference steps. * **audio_input_strength** ([`float`](https://docs.python.org/3/builtins/functions.html#float)) – Denoising strength (0-1). * **Return type:** [`Song`](_autosummary/arioso.base.html.md#arioso.base.Song) * **Returns:** A Song with audio_array populated. # _autosummary/arioso.platforms.riffusion.config.html.md # arioso.platforms.riffusion.config Riffusion platform configuration. # _autosummary/arioso.platforms.riffusion.html.md # arioso.platforms.riffusion Riffusion platform for arioso. ### Modules | [`adapter`](_autosummary/arioso.platforms.riffusion.adapter.html.md#module-arioso.platforms.riffusion.adapter) | Riffusion adapter using the riffusion library or diffusers fallback. | |------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------| | [`config`](_autosummary/arioso.platforms.riffusion.config.html.md#module-arioso.platforms.riffusion.config) | Riffusion platform configuration. | # _autosummary/arioso.platforms.stable_audio.adapter.html.md # arioso.platforms.stable_audio.adapter Stable Audio Open adapter using HuggingFace Diffusers. ### Classes | [`Adapter`](_autosummary/arioso.platforms.stable_audio.adapter.html.md#arioso.platforms.stable_audio.adapter.Adapter)(config) | Stable Audio Open adapter with lazy model loading. | |--------------------------------------------------------------------|------------------------------------------------------| ### *class* arioso.platforms.stable_audio.adapter.Adapter(config) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) Stable Audio Open adapter with lazy model loading. Uses `diffusers.StableAudioPipeline` for local inference. #### generate(prompt, , negative_prompt=None, duration=10.0, num_steps=200, guidance=7.0, seed=None, batch_size=1, sampler='dpmpp-3m-sde', audio_input=None, audio_input_strength=None, \*\*kwargs) Generate audio from a text prompt, optionally conditioned on input audio. * **Parameters:** * **prompt** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str)) – Text description of desired audio. * **negative_prompt** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str)) – Text description of undesired characteristics. * **duration** ([`float`](https://docs.python.org/3/builtins/functions.html#float)) – Length in seconds. * **num_steps** ([`int`](https://docs.python.org/3/builtins/functions.html#int)) – Number of diffusion inference steps. * **guidance** ([`float`](https://docs.python.org/3/builtins/functions.html#float)) – Classifier-free guidance scale. * **seed** ([`int`](https://docs.python.org/3/builtins/functions.html#int)) – Random seed for reproducibility. * **batch_size** ([`int`](https://docs.python.org/3/builtins/functions.html#int)) – Number of waveforms to generate. * **sampler** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str)) – Sampler type for the diffusion process. * **audio_input** – Optional input audio to condition on (audio-to-audio): a Song/AudioResult/bytes/path/(array, sample_rate)/NumPy waveform. Passed to the pipeline as `initial_audio_waveforms` – i.e. the model continues/initializes from this audio. * **audio_input_strength** ([`float`](https://docs.python.org/3/builtins/functions.html#float)) – Accepted for API symmetry but **ignored** – the diffusers `StableAudioPipeline` exposes no denoise/strength control (that is a stable-audio-tools/ComfyUI feature). A warning is emitted if a value is passed alongside `audio_input`. * **Return type:** [`Song`](_autosummary/arioso.base.html.md#arioso.base.Song) * **Returns:** A Song with audio_array populated. # _autosummary/arioso.platforms.stable_audio.config.html.md # arioso.platforms.stable_audio.config Stable Audio Open platform configuration. # _autosummary/arioso.platforms.stable_audio.html.md # arioso.platforms.stable_audio Stable Audio Open platform for arioso. ### Modules | [`adapter`](_autosummary/arioso.platforms.stable_audio.adapter.html.md#module-arioso.platforms.stable_audio.adapter) | Stable Audio Open adapter using HuggingFace Diffusers. | |---------------------------------------------------------------------------------------------------------|----------------------------------------------------------| | [`config`](_autosummary/arioso.platforms.stable_audio.config.html.md#module-arioso.platforms.stable_audio.config) | Stable Audio Open platform configuration. | # _autosummary/arioso.platforms.stable_audio_25.adapter.html.md # arioso.platforms.stable_audio_25.adapter Stable Audio 2.5 adapter (fal.ai): text-to-audio and audio-to-audio. Unlike the local `stable_audio` platform (Stable Audio Open via diffusers, which has no strength knob), the hosted 2.5 audio-to-audio endpoint takes a `strength` in [0, 1]: low values keep the input nearly intact, high values let the prompt take over. That makes it the arioso backend for “the same piece, subtly changed”. ### Classes | [`Adapter`](_autosummary/arioso.platforms.stable_audio_25.adapter.html.md#arioso.platforms.stable_audio_25.adapter.Adapter)(config) | fal.ai Stable Audio 2.5 adapter. | |--------------------------------------------------------------------|------------------------------------| ### *class* arioso.platforms.stable_audio_25.adapter.Adapter(config) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) fal.ai Stable Audio 2.5 adapter. #### generate(prompt, , duration=None, num_steps=8, guidance=1.0, seed=None, audio_input=None, audio_input_strength=0.8, fetch=True, \*\*kwargs) Generate audio from a prompt, or transform `audio_input` toward it. * **Parameters:** * **prompt** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str)) – Text description of the desired audio (required). * **duration** ([`float`](https://docs.python.org/3/builtins/functions.html#float)) – Output length in seconds (1-190). Text-to-audio defaults to 30 s (fal’s own default is its 190 s maximum, the most expensive clip); audio-to-audio defaults to the input’s length. * **num_steps** ([`int`](https://docs.python.org/3/builtins/functions.html#int)) – Denoising steps (`num_inference_steps`, default 8). * **guidance** ([`float`](https://docs.python.org/3/builtins/functions.html#float)) – Prompt adherence (`guidance_scale`, default 1). * **seed** ([`int`](https://docs.python.org/3/builtins/functions.html#int)) – Random seed for reproducibility. * **audio_input** – Audio to transform (path, bytes, Song, URL, …). When given, the audio-to-audio endpoint is used. * **audio_input_strength** ([`float`](https://docs.python.org/3/builtins/functions.html#float)) – Denoising strength for audio-to-audio (0-1, default 0.8); lower keeps more of the input. * **fetch** ([`bool`](https://docs.python.org/3/builtins/functions.html#bool)) – Download the result so `audio_bytes` is populated. * **Return type:** [`Song`](_autosummary/arioso.base.html.md#arioso.base.Song) * **Returns:** A completed Song (`audio_bytes` and `audio_url`). # _autosummary/arioso.platforms.stable_audio_25.config.html.md # arioso.platforms.stable_audio_25.config Stable Audio 2.5 platform configuration (fal.ai hosted). Live docs (verified 2026-10-03): [https://fal.ai/models/fal-ai/stable-audio-25/text-to-audio/api](https://fal.ai/models/fal-ai/stable-audio-25/text-to-audio/api) and [https://fal.ai/models/fal-ai/stable-audio-25/audio-to-audio/api](https://fal.ai/models/fal-ai/stable-audio-25/audio-to-audio/api) # _autosummary/arioso.platforms.stable_audio_25.html.md # arioso.platforms.stable_audio_25 Stable Audio 2.5 (hosted on fal.ai) platform for arioso. ### Modules | [`adapter`](_autosummary/arioso.platforms.stable_audio_25.adapter.html.md#module-arioso.platforms.stable_audio_25.adapter) | Stable Audio 2.5 adapter (fal.ai): text-to-audio and audio-to-audio. | |------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------| | [`config`](_autosummary/arioso.platforms.stable_audio_25.config.html.md#module-arioso.platforms.stable_audio_25.config) | Stable Audio 2.5 platform configuration (fal.ai hosted). | # _autosummary/arioso.platforms.sunoapi.adapter.html.md # arioso.platforms.sunoapi.adapter Suno adapter via sunoapi.org REST API. ### Classes | [`Adapter`](_autosummary/arioso.platforms.sunoapi.adapter.html.md#arioso.platforms.sunoapi.adapter.Adapter)(config, \*[, task_store]) | Adapter for Suno music generation via sunoapi.org. | |--------------------------------------------------------------------------------------|------------------------------------------------------| ### *class* arioso.platforms.sunoapi.adapter.Adapter(config, , task_store=None) Bases: `BaseRestAdapter` Adapter for Suno music generation via sunoapi.org. Handles the distinction between simple generation (prompt only) and custom generation (with lyrics/style via customMode). The sunoapi.org API is callback-based: it returns a taskId immediately and POSTs results to your callBackUrl when generation completes. A no-op placeholder callback URL is used by default, so polling via `get_status()` (or `wait_for_completion=True`) works out of the box. Set the SUNO_CALLBACK_URL env var to a real webhook if you want push notifications. After calling generate(), use get_status() to poll for results, or use generate() with wait_for_completion=True to block until audio is ready. All generation requests and status polls are automatically recorded in a local task store (`SunoTasks`). Access it via the `tasks` property: ```default adapter = Adapter(config) adapter.tasks # SunoTasks Mapping adapter.tasks.last(10) # last 10 tasks adapter.tasks.failed() # all failed tasks ``` #### fetch_audio(song) Download the audio bytes for a Song that has an audio_url. * **Parameters:** **song** ([`Song`](_autosummary/arioso.base.html.md#arioso.base.Song)) – A Song object with a populated audio_url. * **Return type:** [`Song`](_autosummary/arioso.base.html.md#arioso.base.Song) * **Returns:** A new Song with audio_bytes populated. #### get_status(task_id) Check the status of a generation task and return updated Songs. * **Parameters:** **task_id** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str)) – The taskId returned from generate(), upload_extend(), or upload_cover(). * **Return type:** [`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[[`Song`](_autosummary/arioso.base.html.md#arioso.base.Song)] * **Returns:** List of Song objects with current status and audio URLs (if generation is complete). #### get_timestamped_lyrics(song_or_task_id, audio_id=None) Suno’s own alignment of the sung lyric to a finished song. One entry per sung *word* (Suno’s tokens: space-separated, so a whole katakana word such as `バカンス` is one entry), in the order sung — which can differ from the lyric you sent when Suno repeats or drops a line. Times sit on a coarse (~0.16 s) grid and tend to run late, so treat them as windows for a finer aligner rather than as onsets. * **Parameters:** * **song_or_task_id** ([`Song`](_autosummary/arioso.base.html.md#arioso.base.Song) | [`str`](https://docs.python.org/3/builtins/stdtypes.html#str)) – a completed `Song` from `get_status` / `poll_status` (it carries `metadata["task_id"]`), or a taskId. * **audio_id** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str) | [`None`](https://docs.python.org/3/builtins/constants.html#None)) – the song’s audio id; defaults to `song.id`. * **Return type:** [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict) * **Returns:** `{"aligned_words": [...], "hoot_cer": float | None, "raw": dict}` where each aligned word is `{"word", "text", "start", "end", "line_end", "section", "success"}`: `word` is Suno’s raw token (it may carry `[Section]` tags and newlines), `text` the token with those removed, `line_end` whether a lyric line ends there, `section` the label of a section starting at this word (else `None`). Bare section tags are folded onto the next word. * **Raises:** * [**ValueError**](https://docs.python.org/3/builtins/exceptions.html#ValueError) – the Song is not complete, carries no task_id, or Suno has no alignment for it yet. * **hoot_cer\` is Suno's character error rate for the alignment** – #### *property* tasks Local task store (`SunoTasks` Mapping) for recorded requests. #### upload_file(file_path) Upload a local audio file and return a public URL. Uses the sunoapi.org file upload API. Uploaded files are temporary and automatically deleted after 3 days. * **Parameters:** **file_path** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str)) – Path to the local audio file. * **Return type:** [`str`](https://docs.python.org/3/builtins/stdtypes.html#str) * **Returns:** Public URL of the uploaded file. # _autosummary/arioso.platforms.sunoapi.config.html.md # arioso.platforms.sunoapi.config Suno (via sunoapi.org) platform configuration. # _autosummary/arioso.platforms.sunoapi.html.md # arioso.platforms.sunoapi Suno platform (via sunoapi.org) for arioso. ### Modules | [`adapter`](_autosummary/arioso.platforms.sunoapi.adapter.html.md#module-arioso.platforms.sunoapi.adapter) | Suno adapter via sunoapi.org REST API. | |--------------------------------------------------------------------------------------------------------|------------------------------------------------| | [`config`](_autosummary/arioso.platforms.sunoapi.config.html.md#module-arioso.platforms.sunoapi.config) | Suno (via sunoapi.org) platform configuration. | | [`task_store`](_autosummary/arioso.platforms.sunoapi.task_store.html.md#module-arioso.platforms.sunoapi.task_store) | Local task store for Suno API requests. | # _autosummary/arioso.platforms.sunoapi.task_store.html.md # arioso.platforms.sunoapi.task_store Local task store for Suno API requests. Provides a `collections.abc.Mapping` interface over locally-persisted task records, so you can list, filter, and retrieve past Suno generation requests without depending on a (non-existent) “list all” API endpoint. Each task is stored as a JSON file keyed by `taskId`. The store records request parameters, status, timestamps, and the full API response. Typical usage: ```default from arioso.platforms.sunoapi.task_store import SunoTasks tasks = SunoTasks() # uses default data dir tasks['5c79...be8e'] # get one task record list(tasks) # all task IDs len(tasks) # how many tasks # Filtered views (return new Mapping objects): tasks.last(20) # last 20 by creation time tasks.since(hours=24) # created in last 24 hours tasks.status('SUCCESS') # only successful tasks tasks.status('PENDING') # only pending tasks tasks.failed() # all failed tasks ``` ### Classes | [`SunoTasks`](_autosummary/arioso.platforms.sunoapi.task_store.html.md#arioso.platforms.sunoapi.task_store.SunoTasks)([root_dir]) | A `Mapping[str, dict]` of Suno task records persisted as JSON files. | |--------------------------------------------------------------------------|------------------------------------------------------------------------| ### *class* arioso.platforms.sunoapi.task_store.SunoTasks(root_dir=None) Bases: [`Mapping`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Mapping) A `Mapping[str, dict]` of Suno task records persisted as JSON files. Keys are task IDs, values are task-record dicts with fields: ```default task_id, operation, status, created_at, updated_at, request_params, response ``` The store is backed by individual `.json` files in *root_dir*. #### failed() Return all tasks with an error status. * **Return type:** `_FilteredTaskView` #### last(n=20) Return a view of the most recent *n* tasks (newest first). * **Return type:** `_FilteredTaskView` #### pending() Return all tasks that are still pending or in progress. * **Return type:** `_FilteredTaskView` #### save(record) Persist a task record (create or overwrite). * **Return type:** [`None`](https://docs.python.org/3/builtins/constants.html#None) #### since(, hours=0, minutes=0) Return tasks created within the last *hours* + *minutes*. * **Return type:** `_FilteredTaskView` #### status(status_value) Return tasks matching *status_value* (case-insensitive). * **Return type:** `_FilteredTaskView` #### succeeded() Return all tasks that completed successfully. * **Return type:** `_FilteredTaskView` #### update(task_id, , status='', response=None) Update an existing record’s status and/or response. # _autosummary/arioso.platforms.udio.adapter.html.md # arioso.platforms.udio.adapter Udio adapter via udio-wrapper (unofficial). ### Classes | [`Adapter`](_autosummary/arioso.platforms.udio.adapter.html.md#arioso.platforms.udio.adapter.Adapter)(config) | Adapter for Udio using the unofficial udio-wrapper package. | |--------------------------------------------------------------------|---------------------------------------------------------------| ### *class* arioso.platforms.udio.adapter.Adapter(config) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) Adapter for Udio using the unofficial udio-wrapper package. Requires `pip install udio-wrapper` and a valid auth cookie set in the UDIO_AUTH_COOKIE environment variable. #### generate(prompt, , lyrics='', seed=-1, audio_input='', \*\*kwargs) Generate music via Udio. * **Parameters:** * **prompt** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str)) – Text description of desired music. * **lyrics** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str)) – Custom lyrics text. * **seed** ([`int`](https://docs.python.org/3/builtins/functions.html#int)) – Random seed (-1 for random). * **audio_input** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str)) – Path to conditioning audio file. * **Return type:** [`Song`](_autosummary/arioso.base.html.md#arioso.base.Song) * **Returns:** A Song with audio_url populated. # _autosummary/arioso.platforms.udio.config.html.md # arioso.platforms.udio.config Udio platform configuration (via udio-wrapper). # _autosummary/arioso.platforms.udio.html.md # arioso.platforms.udio Udio platform (via UdioWrapper) for arioso. ### Modules | [`adapter`](_autosummary/arioso.platforms.udio.adapter.html.md#module-arioso.platforms.udio.adapter) | Udio adapter via udio-wrapper (unofficial). | |-------------------------------------------------------------------------------------------------|-------------------------------------------------| | [`config`](_autosummary/arioso.platforms.udio.config.html.md#module-arioso.platforms.udio.config) | Udio platform configuration (via udio-wrapper). | # _autosummary/arioso.platforms.yue.adapter.html.md # arioso.platforms.yue.adapter YuE adapter supporting fal.ai REST API and local CLI backends. ### Classes | [`Adapter`](_autosummary/arioso.platforms.yue.adapter.html.md#arioso.platforms.yue.adapter.Adapter)(config) | YuE adapter with dual backend support. | |--------------------------------------------------------------------|------------------------------------------| ### *class* arioso.platforms.yue.adapter.Adapter(config) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) YuE adapter with dual backend support. Prefers the fal.ai hosted API when `FAL_KEY` is set. Falls back to local subprocess invocation of `infer.py` otherwise. #### generate(prompt, , lyrics='', duration=30.0, model='m-a-p/YuE-s1-7B-anneal-en-cot', batch_size=4, max_tokens=3000, repetition_penalty=1.1, audio_input='', \*\*kwargs) Generate music from genre description and lyrics. * **Parameters:** * **prompt** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str)) – Genre/style description (mapped to `genre_txt`). * **lyrics** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str)) – Lyrics text (mapped to `lyrics_txt`). * **duration** ([`float`](https://docs.python.org/3/builtins/functions.html#float)) – Desired length in seconds (converted to segments). * **model** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str)) – Stage-1 model identifier. * **batch_size** ([`int`](https://docs.python.org/3/builtins/functions.html#int)) – Stage-2 batch size. * **max_tokens** ([`int`](https://docs.python.org/3/builtins/functions.html#int)) – Maximum new tokens for generation. * **repetition_penalty** ([`float`](https://docs.python.org/3/builtins/functions.html#float)) – Token repetition penalty. * **audio_input** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str)) – Path to a vocal track prompt file, if any. * **Return type:** [`Song`](_autosummary/arioso.base.html.md#arioso.base.Song) * **Returns:** A Song with audio_url or audio_bytes populated. # _autosummary/arioso.platforms.yue.config.html.md # arioso.platforms.yue.config YuE platform configuration. # _autosummary/arioso.platforms.yue.html.md # arioso.platforms.yue YuE platform for arioso. ### Modules | [`adapter`](_autosummary/arioso.platforms.yue.adapter.html.md#module-arioso.platforms.yue.adapter) | YuE adapter supporting fal.ai REST API and local CLI backends. | |------------------------------------------------------------------------------------------------|------------------------------------------------------------------| | [`config`](_autosummary/arioso.platforms.yue.config.html.md#module-arioso.platforms.yue.config) | YuE platform configuration. | # _autosummary/arioso.registry.html.md # arioso.registry Platform registry with auto-discovery and lazy loading. ### Functions | [`discover_platforms`](_autosummary/arioso.registry.html.md#arioso.registry.discover_platforms)() | Scan arioso.platforms for valid platform packages. | |---------------------------------------------------------------------------------------------|-------------------------------------------------------------------| | [`get_platform`](_autosummary/arioso.registry.html.md#arioso.registry.get_platform)(name) | Get registered platform info, lazy-loading the adapter if needed. | | [`list_platforms`](_autosummary/arioso.registry.html.md#arioso.registry.list_platforms)() | Return names of all registered platforms. | | [`register_platform`](_autosummary/arioso.registry.html.md#arioso.registry.register_platform)(name, config[, adapter]) | Manually register a platform (for third-party plugins). | ### arioso.registry.discover_platforms() Scan arioso.platforms for valid platform packages. A valid platform package is a directory under arioso/platforms/ that: 1. Is a Python package (_\_init_\_.py exists) 2. Contains a config.py with a PLATFORM_CONFIG dict * **Return type:** [`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str)] * **Returns:** List of discovered platform names. ### arioso.registry.get_platform(name) Get registered platform info, lazy-loading the adapter if needed. * **Parameters:** **name** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str)) – Platform identifier. * **Return type:** [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict) * **Returns:** Dict with ‘config’ and ‘adapter’ keys. * **Raises:** [**KeyError**](https://docs.python.org/3/builtins/exceptions.html#KeyError) – If the platform is not found. ### arioso.registry.list_platforms() Return names of all registered platforms. * **Return type:** [`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str)] ### arioso.registry.register_platform(name, config, adapter=None) Manually register a platform (for third-party plugins). * **Parameters:** * **name** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str)) – Platform identifier. * **config** ([`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)) – PLATFORM_CONFIG dict following the standard schema. * **adapter** ([`Any`](https://docs.python.org/3/library/typing.html#typing.Any)) – Optional pre-instantiated adapter object or class. # _autosummary/arioso.services.html.md # arioso.services ### arioso.services *= ServiceCollection(ace_step, beatoven, elevenlabs, harmonai, jen, loudly, lyria2, lyria_rt, mubert, musicgen, riffusion, stable_audio, stable_audio_25, sunoapi, udio, yue)* Lazy mapping of platform names to `ServiceHandle` objects. Supports both `services["sunoapi"]` and `services.sunoapi`, both returning the same `ServiceHandle`. # _autosummary/arioso.tools.html.md # arioso.tools High-level tools for common arioso workflows (submit, poll, download). ### Functions | [`download_songs`](_autosummary/arioso.tools.html.md#arioso.tools.download_songs)(songs, target_folder, \*[, ...]) | Download completed songs to *target_folder*. | |----------------------------------------------------------------------------------------------------|----------------------------------------------------------------------| | [`ensure_adapter`](_autosummary/arioso.tools.html.md#arioso.tools.ensure_adapter)([adapter]) | Return a ready-to-use platform adapter. | | [`extract_style`](_autosummary/arioso.tools.html.md#arioso.tools.extract_style)(filename) | Parse style from a filename like `barry_{key}_{bpm}bpm_{Style}.wav`. | | [`poll_status`](_autosummary/arioso.tools.html.md#arioso.tools.poll_status)(task_id, \*[, poll_interval, ...]) | Poll until a task completes. | | [`safe_name`](_autosummary/arioso.tools.html.md#arioso.tools.safe_name)(text) | Convert arbitrary text to a filesystem-safe string. | | [`submit_cover`](_autosummary/arioso.tools.html.md#arioso.tools.submit_cover)(source_path, \*[, style, ...]) | Submit an upload-cover job. | | [`wav_to_mp3`](_autosummary/arioso.tools.html.md#arioso.tools.wav_to_mp3)(wav_path, \*[, max_duration]) | Convert wav to a trimmed mp3. | ### arioso.tools.download_songs(songs, target_folder, , name_prefix='cover', adapter=None) Download completed songs to *target_folder*. Returns list of saved paths. ### arioso.tools.ensure_adapter(adapter='sunoapi') Return a ready-to-use platform adapter. `adapter` can be: - An existing adapter instance — returned as-is. - A platform config dict — instantiated via its `Adapter` class. - A string that is a valid platform name (e.g. `"sunoapi"`) — loaded from the arioso registry. - `None` — falls back to `DFLT_PLATFORM`. Raises `ValueError` for unrecognised inputs. ### arioso.tools.extract_style(filename) Parse style from a filename like `barry_{key}_{bpm}bpm_{Style}.wav`. ### arioso.tools.poll_status(task_id, , poll_interval=15, timeout=600, adapter=None) Poll until a task completes. Returns list of completed Song objects. ### arioso.tools.safe_name(text) Convert arbitrary text to a filesystem-safe string. ### arioso.tools.submit_cover(source_path, \*, style='', prompt='', instrumental=True, model='V5', audio_weight=0.5, style_weight=0.5, source_prep=functools.partial(, max_duration=480), adapter='sunoapi') Submit an upload-cover job. Returns `(task_id, source_path)`. * **Parameters:** * **source_path** – Path to source audio file. * **source_prep** – Callable `(path) -> path` to prepare the source file before upload (e.g. convert wav to mp3). Defaults to [`wav_to_mp3()`](_autosummary/arioso.tools.html.md#arioso.tools.wav_to_mp3) (trimmed to *max_duration*). * **adapter** – Platform adapter, config dict, platform name, or `None`. The caller is responsible for cleaning up *source_path* when done. ### arioso.tools.wav_to_mp3(wav_path, , max_duration=480) Convert wav to a trimmed mp3. Returns path to a temp mp3 file. The caller is responsible for deleting the temp file when done. # _autosummary/arioso.translation.html.md # arioso.translation Parameter translation layer. Translates between the unified affordance names and each platform’s native parameter names, applying type coercions along the way. ### Module Attributes | [`ALWAYS_RAISE_UNSUPPORTED`](_autosummary/arioso.translation.html.md#arioso.translation.ALWAYS_RAISE_UNSUPPORTED) | Affordances that always raise on an unsupported platform, regardless of that platform's own `on_unsupported_param` policy. | |-----------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------| ### Functions | [`check_supported_params`](_autosummary/arioso.translation.html.md#arioso.translation.check_supported_params)(kwargs, config, \*[, ...]) | Warn or raise for kwargs not declared in a platform's `supported_affordances`. | |------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------| | [`make_generate_func`](_autosummary/arioso.translation.html.md#arioso.translation.make_generate_func)(config) | Build a generate() callable from a platform config. | | [`make_kwargs_trans`](_autosummary/arioso.translation.html.md#arioso.translation.make_kwargs_trans)(param_map, \*[, ...]) | Build a kwargs translation function from a platform's param_map. | ### arioso.translation.ALWAYS_RAISE_UNSUPPORTED *= ('lyrics',)* Affordances that always raise on an unsupported platform, regardless of that platform’s own `on_unsupported_param` policy. Losing these silently is losing *content*, not a quality knob – e.g. an instrumental with none of the caller’s words in it, with no signal that happened. See thorwhalen/arioso#3. ### arioso.translation.check_supported_params(kwargs, config, , always_raise=('lyrics',)) Warn or raise for kwargs not declared in a platform’s `supported_affordances`. `on_unsupported_param` was, until thorwhalen/arioso#3, only ever enforced inside [`make_kwargs_trans()`](_autosummary/arioso.translation.html.md#arioso.translation.make_kwargs_trans) – reached solely by the REST-fallback `generate` built by [`make_generate_func()`](_autosummary/arioso.translation.html.md#arioso.translation.make_generate_func). Every platform that ships a custom `adapter.py` (which is all 14, as of this writing) never went through that translator: its `Adapter.generate(..., **kwargs)` absorbed and silently dropped anything unsupported, regardless of the config’s declared policy. Call this once, uniformly, before dispatching to *any* adapter – see `arioso.generate`/`arioso.generate_many`. This only validates; it does not translate or drop keys itself. The caller’s kwargs are passed to the adapter unchanged either way. * **Parameters:** * **kwargs** ([`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)) – The unified-name kwargs about to be passed to an adapter (must not include `prompt`). * **config** ([`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)) – The platform’s `PLATFORM_CONFIG` dict. * **always_raise** ([`tuple`](https://docs.python.org/3/builtins/stdtypes.html#tuple)) – Affordance names that raise unconditionally when unsupported, overriding the platform’s own policy. * **Return type:** [`None`](https://docs.python.org/3/builtins/constants.html#None) ### arioso.translation.make_generate_func(config) Build a generate() callable from a platform config. This is the fallback when no custom adapter.py is provided. For REST API platforms, it builds the HTTP function from the config and wraps it with parameter translation and output normalization. * **Parameters:** **config** ([`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)) – A PLATFORM_CONFIG dict. * **Return type:** [`Callable`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable) * **Returns:** A callable that accepts unified affordance kwargs and returns a Song. ### arioso.translation.make_kwargs_trans(param_map, , on_unsupported='warn', passthrough=()) Build a kwargs translation function from a platform’s param_map. The returned function transforms: ```default {common_name: value, ...} -> {native_name: coerced_value, ...} ``` * **Parameters:** * **param_map** ([`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)) – Dict mapping common affordance names to native config dicts. Each value has keys: `native_name` (str), `coerce` (optional callable), `adapter_handled` (optional bool). * **on_unsupported** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str)) – What to do with params not in param_map. One of ‘warn’, ‘raise’, or ‘ignore’. * **passthrough** – Adapter-only keyword names (a config’s `adapter_params`) passed through untranslated and unwarned. * **Return type:** [`Callable`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable)[[[`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)], [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)] * **Returns:** A function that translates outer kwargs to inner kwargs. # about-this-build.html.md # About this build This documentation was built on **2026-10-14 04:26 UTC** from commit 4223c54 on branch main, for **arioso 0.0.24** (from pyproject.toml). #### NOTE Nothing suggests a mismatch: the tree was clean at the commit above, and the documented version is the one on PyPI. ## Source | | | |---------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------| | Commit | 4223c544da88760863bddff269ec385b261c06ce | | Branch | main | | Tags at this commit | 0.0.24 | | Working tree | clean | | Remote | https://github.com/thorwhalen/arioso | ## Continuous integration | | | |--------------|--------------------------------------------------------------------------------------------| | Repository | thorwhalen/arioso | | Run | 38511257064 | | Ref | refs/heads/main | | Event commit | 85fe6841bda6d4454619cea60077d218676e55c4 (in the history of the built commit) | ## Tools | | | |----------|---------| | epythet | 0.2.17 | | Sphinx | 9.1.0 | | docutils | 0.22.4 | | Python | 3.12.15 | ## Configuration as resolved | | | |---------------|-------------------------------------------------------------------| | theme | auto (Sphinx theme pydata_sphinx_theme) | | accent | #923240 | | api_generator | autosummary | | ignore | tests/, scrap/, examples/ | | agent_outputs | true | | aggregates | md | | ai_artifacts | true | ## Package on PyPI Latest release: 0.0.24, the same as the documented version. ## Reproduce ```bash git clone https://github.com/thorwhalen/arioso && cd arioso git checkout 4223c544da88760863bddff269ec385b261c06ce pip install "epythet==0.2.17" epythet quickstart . --ignore tests/ scrap/ examples/ ``` The same data, for machines: build_info.json (schema version 1). # ai-agents.html.md # For AI agents `arioso` ships artifacts for coding agents alongside its code. This page lists them, says where each lives in the repository, and points at the machine-readable copies of this documentation. ## Skills Skills are folders holding a `SKILL.md` (the [Agent Skills](https://agentskills.io) format): a description that tells an agent when to use it and a body with the procedure. Install one into your agent with `gh skill` (any host: `--agent claude-code`, `copilot`, `cursor`, `codex`, `gemini`), or use the copy bundled in the wheel. ### `arioso` Generate music with AI using the `arioso` package — one Python interface over 16 music-generation backends (Suno, ElevenLabs Music, Udio, YuE, ACE-Step, MusicGen, Stable Audio, Stable Audio 2.5, Riffusion, Harmonai, Lyria, Mubert, Beatoven, Loudly, Jen). Use when the user wants to “make a song”, “generate music”, “write a song about X”, “turn this poem/text/script into a song”, “set these lyrics to music”, “text to music”, “make a theme tune”, “I need background music”, or “a royalty-free instrumental track” — or when they name a platform (Suno, ElevenLabs Music, Udio, MusicGen, Stable Audio, Riffusion, Lyria). Covers the one-line call, which five backends can actually SING lyrics you wrote (the other eleven drop them silently), the Suno customMode title/genre requirement, which backends are free versus paid, polling an async job, and writing the audio to disk. ```bash gh skill install thorwhalen/arioso arioso --agent claude-code ``` Source: [`arioso/data/skills/arioso`](https://github.com/thorwhalen/arioso/tree/HEAD/arioso/data/skills/arioso) (bundled with the pip package). The bundled skills are also on disk after `pip install arioso`, under the package’s `data/skills/` directory; link them into an agent without network access with `skill link-skills `. ## Instruction files Files agents read before working in this repository. - [`CLAUDE.md`](https://github.com/thorwhalen/arioso/tree/HEAD/CLAUDE.md): read by Claude Code ## Machine-readable documentation This site publishes the same documentation in forms that fit an agent’s context window: - [`llms.txt`](https://thorwhalen.github.io/arioso/llms.txt): an index of every page with a one-line description ([llms.txt](https://llmstxt.org) format) - [`arioso.md`](https://thorwhalen.github.io/arioso/arioso.md): the whole documentation as one Markdown file - `.html.md`: a rendered Markdown twin of every page, advertised from each page’s `` with `` - [`objects.inv`](https://thorwhalen.github.io/arioso/objects.inv): the Sphinx inventory: a symbol-to-URL index (`sphobjinv convert plain objects.inv -`) # api.html.md # API reference | [`arioso`](_autosummary/arioso.html.md#module-arioso) | Arioso - Unified facade for AI music generation platforms. | |-------------------------------------------------------------------------|--------------------------------------------------------------|