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
pip install arioso
Quick start
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
Command line
Installing arioso also installs an arioso command (python -m arioso does the same).
arioso generate "warm lo-fi piano" --platform musicgen --duration 10 -o out.wav
arioso generate "ambient pads" --platform stable_audio --model stabilityai/stable-audio-open-1.0 --seed 7 -o pads.wav
arioso platforms
generate writes the audio and prints the path it wrote. A waveform from a local model is written as WAV (with soundfile when installed, else the standard library's wave); encoded audio from a hosted platform keeps its format, and the file's suffix follows it. --model and --seed are passed on only when given.
platforms lists every platform with its access type, weights licence and whether its output may be used commercially (yes, no, conditional, unclear when the terms are not settled (licence unstated, disputed or withdrawn, or a doubtful training-data chain), or provider terms for hosted models whose service terms decide). The same table is arioso.platform_table() in Python, and each platform's weights_license and commercial_use are in arioso.get_platform_info(name). MusicGen's weights are CC-BY-NC-4.0, so its output is not for commercial use.
Local torch platforms (MusicGen on transformers, Stable Audio Open) run on CUDA, else Apple MPS, else CPU; set ARIOSO_TORCH_DEVICE to force one.
Comparing platforms
compare renders the same prompts with several platforms and measures each take:
arioso compare stable_audio_3,magenta_rt,ace_step:runtime=local --prompts prompts.json --duration 10
A contender is a platform with optional key=value options (musicgen:model=facebook/musicgen-small). Each one runs in a fresh process, one after the other, so only one model is in memory at a time and its peak memory is its own: on macOS the peak physical footprint, which counts Metal allocations, on Linux the peak resident set, in GB (10^9 bytes), for the process and, sampled while it runs, for the processes it starts (a runtime's worker, or one process per take). Every take becomes one JSON line in <out_dir>/results.jsonl: model load plus warm-up time, generation time, real-time factor (generation time over the seconds that came back), peak memory, available memory before the run, the weights licence, and objective checks: peak level and clipping (takes are kept as float WAVs, so a peak over full scale shows), and, when denote is installed, the detected tempo against the prompt's bpm (half and double time forgiven) and the estimated key against its key. A check that cannot run says why under checks_skipped. Takes of one run go to <out_dir>/<run id>/<contender>/<prompt id>.wav with a page of players beside them (index.html), and the command prints a progress line per take, then a summary per contender.
Load times compare like with like only between runtimes of the same kind: a runtime that keeps a worker (Magenta RealTime, ACE-Step) loads once, in the warm-up, while one that starts a process per take (Stable Audio 3) loads in every take, so its load is inside its real-time factor.
Without --prompts it uses three built-in prompts (a groove at 100 BPM, an accompaniment in C major, a loop at 85 BPM). A prompts file is a JSON list of {"id", "text", "bpm", "key", "melody", "duration"} (only text is required; a melody path is passed to platforms that take one). Platforms that may call a paid hosted service are refused unless you pass --allow-hosted: anything that is not a python_lib or local_runtime, has provider terms, or takes any credential (even an optional one, as yue takes a fal key); runtime=local counts as local only on a platform that has a local runtime (ace_step). --min-free-gb skips a contender when the machine is short of memory.
In Python, arioso.compare.compare(contenders, prompts) yields the same records. Its seams are runner= (how a contender is run and measured: in_child_process, with python=, or in_this_process), scorer= (audio to a dict of checks), preload= (modules that register third-party platforms, run here and in each child; --preload on the command line) and timeout= (seconds before a contender is killed with every process it started; --timeout). A killed or crashing contender keeps the takes it finished. Worker memory is sampled every 0.1 s, so it is a lower bound: memory a process takes just before exiting can be missed.
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:
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
To extend a recording rather than transform it, pass it as continue_from to musicgen. The last prompt_seconds (default 10) of the audio prompt the model, which writes extend_seconds (default duration) of what comes next, chained over rounds calls. The result is the original followed by the continuation; the continuation alone is in song.metadata["continuation"]. It runs locally, so it also extends audio that a hosted extend route refuses (Suno's upload_extend rejects uploads that match a catalogued composition).
longer = arioso.generate(
"warm piano trio",
platform="musicgen",
model="facebook/musicgen-medium",
continue_from="take.wav",
prompt_seconds=10,
extend_seconds=20,
rounds=2,
)
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.
Seeds: a melody over a drone
To make a generator keep a known melody with no harmony (a Suno upload-cover, MusicGen-melody), give it the melody alone over a drone: a cover keeps its source's harmony static, so a source with no harmony gives takes that hold the drone. arioso.seeds builds that source from a recording or a score (pip install 'arioso[seeds]'; separating a voice from a mix goes through denote, which also needs torch and torchaudio).
from arioso.seeds import melody_contour, melody_over_drone
from arioso.analysis import drone_report, melody_match
contour = melody_contour(
"song.mid"
) # one MIDI track's skyline, with glides and vibrato
contour = melody_contour(
"song.mp3"
) # or a recording: voice separated, f0 tracked, cleaned
seed, sr = melody_over_drone(
contour.transposed(-3), "C#"
) # bowed line over a tanpura on C#
drone_report(take, sr, sa="C#").holds() # does a take hold the drone?
melody_match(take, seed, sr) # does it keep the tune? (~0.9 vs ~0.45 for another song)
Every step is a seam: audio_contour(..., separator=, f0_tracker=), melody_over_drone(..., drone=, timbre=). A low (male) line is lifted by octaves above the drone's register (floor_midi), where it would otherwise fail drone_report.
A real tanpura sounds less synthetic than tanpura(): pass a recording as drone= (or drone=recorded_drone(y, sr)). It is retuned to Sa by varispeed (up to max_shift, 2 semitones by default) and looped with crossfades. A CC0 one to start from: "Tanpura in E" on Freesound.
For a source in a generator's own phrasing, musicgen_variation(voice, "C#", prompt="slow sarangi", transpose=..., slow=1.2) runs MusicGen-melody on the voice over the drone, high-passes its take below the drone's band, and puts the drone back underneath.
Platforms
19 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] |
| Stable Audio 3 | Local (MLX runtime, Apple Silicon) | None | runtime: see below |
| Magenta RealTime 2 | Local (MLX runtime, Apple Silicon) | None | runtime: see below |
| Foundation-1 | Local (stable-audio-tools, own environment) | None | built on first use: see below |
| 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, or local ACE-Step 1.5 (runtime="local") |
FAL_KEY (fal only) |
pip install arioso[ace-step] |
| Udio | Unofficial wrapper | UDIO_AUTH_COOKIE |
pip install arioso[udio] |
# 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, with one of three libraries:
-
MLX (Apple Silicon, text prompts): Apple's port in
ml-explore/mlx-examples, run in its own environment by a worker. On an M1 Max a 10 s clip ofmusicgen-smalltakes about 11 s, against 3 to 6 minutes withtransformerson the GPU. It is used for text takes whenever its runtime is installed:git init --quiet ~/.local/share/arioso/runtimes/mlx-examples git -C ~/.local/share/arioso/runtimes/mlx-examples fetch --quiet --depth 1 https://github.com/ml-explore/mlx-examples 796f5b53cab69a3d48a44233ce21aae889e94a08 git -C ~/.local/share/arioso/runtimes/mlx-examples checkout --quiet --detach 796f5b53cab69a3d48a44233ce21aae889e94a08 cd ~/.local/share/arioso/runtimes/mlx-examples/musicgen && uv venv .venv --python 3.12 && uv pip install --python .venv/bin/python -r requirements.txt(or point
$ARIOSO_MLX_EXAMPLES_DIRat an existing checkout). The checkout is pinned to that commit, the one arioso was measured on: a runtime at another commit is not used for automatic selection (arioso warns and falls back to the next backend), and the error says how to move it.python -c "from arioso.platforms.musicgen.backends import MlxBackend; print(MlxBackend.runtime().hint())"prints the commands for the current pin. It runs Meta's mono text checkpoints (facebook/musicgen-small,-medium,-large);top_pis ignored there, and takes past MusicGen's 30 s context are warned about. Alternating text takes with melody or continuation takes reloads a model at each switch, so batch them by kind. -
audiocraft, Meta's library, when it imports.
-
transformers otherwise. On Apple Silicon the text checkpoints run on the CPU unless
ARIOSO_TORCH_DEVICE=mps: on MPS they were slower than the CPU and grew GPU memory with every step. The melody checkpoint keeps MPS.
Melody-following and continuation always use audiocraft or transformers. ARIOSO_MUSICGEN_BACKEND=mlx|audiocraft|transformers forces one (mlx for text takes only).
song = arioso.generate(
"chill lofi beats",
platform="musicgen",
duration=10,
temperature=0.8,
guidance=3.0,
model="facebook/musicgen-small", # or medium, large, melody
)
Local models in their own environments (Stable Audio 3, Magenta RealTime 2, ACE-Step 1.5)
Some local models pin library versions (MLX, torch) that cannot share an environment with each other, so arioso runs them in their own: each platform names a runtime directory and the commands that install it, and a missing one raises RuntimeNotInstalled with those commands. Runtimes live under ~/.local/share/arioso/runtimes/<name> unless $ARIOSO_RUNTIMES_DIR or the platform's own variable ($ARIOSO_SA3_DIR, $ARIOSO_MAGENTA_RT_DIR, $ARIOSO_ACE_STEP_DIR, $ARIOSO_MLX_EXAMPLES_DIR for MusicGen on MLX) points elsewhere. Magenta RealTime, ACE-Step and MusicGen on MLX keep one worker process alive, so the model loads once per session.
import arioso
# Stable Audio 3 (Stability's MLX build, Apple Silicon): model="sm-music" (default), "sm-sfx" or "medium"
song = arioso.generate(
"lo-fi hip hop loop, 85 BPM, mellow Rhodes",
platform="stable_audio_3",
duration=11.29,
seed=1,
)
# Magenta RealTime 2 (MLX, Apple Silicon): style from text or from a reference clip
song = arioso.generate("funky drum and bass groove", platform="magenta_rt", duration=10)
# ACE-Step 1.5 run locally (fal.ai stays the default; $ARIOSO_ACE_STEP_RUNTIME=local changes it): explicit BPM and key
song = arioso.generate(
"acoustic guitar and soft piano",
platform="ace_step",
runtime="local",
bpm=100,
key="C Major",
duration=30,
)
| platform | weights licence | commercial use |
|---|---|---|
stable_audio_3 |
Stability AI Community License (+ Gemma terms for its text encoder) | free under US$1M annual revenue |
magenta_rt |
CC-BY-4.0 | yes, with attribution |
ace_step (local) |
MIT | yes |
foundation_1 |
Stability AI Community License | free under US$1M annual revenue |
Foundation-1 (local loops and one-shots, stable-audio-tools)
Foundation-1 is a Stable Audio Open 1.0 fine-tune for instrument loops and one-shots, prompted with tags: instrument family and sub-family, timbre, notation and FX, then bars, tempo and key ("Synth Lead, Warm, Arp, Medium Reverb, 8 Bars, 140 BPM, E minor"; the tag list is in the model card's Master_Tag_Reference.md). The prompt is passed through; bpm and key are appended as those tags. With a tempo the clip is exactly bars bars of 4/4 (bars=4 or 8, else the count nearest to duration); without one, duration is the clip length (at most 20 s). Tags already in the prompt are read (a short key such as Am is spelt out; a contradiction with the arguments is an error), and missing ones go in the card's order. note="C3" makes a one-shot at that pitch (Target Note, C3 appended, 3 s by default). Three checkpoints share one model: model="foundation-1" (loops, the default), "1.2-samples" (loops and one-shots) and "1.2-keybeds" (pitch-consistent one-shots; with note= the prompt takes that checkpoint's single-note form, Keybed, Timbre Profile, ..., Target Note, C3).
stable-audio-tools pins its own torch and Python 3.10, so arioso builds an environment for it with uv on first use (once, under ~/.local/share/arioso/envs/foundation-1, or $ARIOSO_ENVS_DIR; $ARIOSO_FOUNDATION_1_ENV names an existing one instead) from pinned requirements resolved with --exclude-newer, and runs the model in one worker process there. Each checkpoint (2.4 GB) and the T5-base text encoder download once to the Hugging Face cache, at pinned revisions, and are read from it without network calls afterwards. On a Mac it needs Apple Silicon (torch 2.7 has no Intel macOS wheels). It runs on CUDA, Apple MPS or the CPU (device= to choose). On MPS it samples with plain classifier-free guidance, as Stable Audio Open does: stable-audio-tools' default adaptive projected guidance computes in float64, which MPS does not support, so it is turned off, and PYTORCH_ENABLE_MPS_FALLBACK=1 lets any operator MPS lacks run on the CPU.
import arioso
# A 4-bar loop at 100 BPM in A minor (9.6 s)
song = arioso.generate(
"Rhodes Piano, Warm, Chord Progression, Low Reverb",
platform="foundation_1",
bpm=100,
key="Am",
bars=4,
seed=7,
)
song.metadata[
"prompt_sent"
] # 'Rhodes Piano, Warm, Chord Progression, Low Reverb, 4 Bars, 100 BPM, A minor'
# A one-shot: no tempo, so duration is the length
song = arioso.generate(
"Grand Piano, Near, Bright, Hit",
platform="foundation_1",
model="1.2-samples",
duration=3,
)
Measured on an M1 Max (64 GB, MPS, the default 100 steps): a 10 s clip takes 70 s once the model is loaded (92 s for the first, loading included), about 7 times real time, and the worker process peaks at 14 GB.
Building playable sampler instruments from the keybeds checkpoint (many notes from one descriptor, sliced and mapped) is not covered yet: see #66.
ElevenLabs
Needs ELEVENLABS_API_KEY environment variable.
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.
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.
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:
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):
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:
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:
# 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:
# 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:
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 | Orchestral AI composition. Desktop/web DAW with 250+ style presets, direct BPM/key/instrument control. | genre, bpm, key, instruments, duration |
| ACE Studio | acestudio.ai | AI vocal synthesis DAW plugin. 140+ voice models for singing voice generation. | voice_id, lyrics, instruments |
| Boomy | boomy.com | AI song creation with Auto Vocal and streaming platform distribution. Enterprise-only API. | prompt, voice_id, instrumental |
| Soundraw | soundraw.io | AI music generation for content creators. Enterprise B2B API only ($11/mo consumer web app). | genre, duration, energy |
| CassetteAI | cassetteai.com | Prompt-based music generation. Web-only, no known API. | prompt, duration |
| Musicfy | 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 <PLATFORM>_REFERENCE.md in its directory under
arioso/platforms/ with platform-specific prompt engineering guidance, API
details, and links to further reading.
Architecture
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_CONFIGdict 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.
durationseconds tomusic_length_msmilliseconds for ElevenLabs) for platforms served by the config-generated REST adapter. A platform with its ownadapter.pytakes unified names directly, on every path (arioso.generateandarioso.services.<platform>.generatealike). - Leverages existing libraries. Uses ho for OpenAPI-to-Python-function generation, i2 for signature manipulation and function wrapping.
Metadata
Release files for arioso 0.0.53
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| arioso-0.0.53.tar.gz | 184.6 kB | Without provenance | Details for arioso-0.0.53.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| arioso-0.0.53-py3-none-any.whl | Python 3 | none | any | Details for arioso-0.0.53-py3-none-any.whl |
Total release size: 401.7 kB
Release files / arioso-0.0.53.tar.gz
| Download URL | arioso-0.0.53.tar.gz |
|---|---|
| Size | 184.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
d5257c6356392123d2c755477929dbb232934b2edbe10e2076eac8e6a0ce30d0
|
|
BLAKE2b-256 checksum How to use checksums |
a76070a66172117362407f034f1a385787faa7e403e0c26228a39ff6a66bdf63
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.13.7 {"installer":{"name":"uv","version":"0.13.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / arioso-0.0.53-py3-none-any.whl
| Download URL | arioso-0.0.53-py3-none-any.whl |
|---|---|
| Size | 217.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
58811da148904cc7fcd8ea3caa517086ca04eaf61438ae6f87f1bb729b55610f
|
|
BLAKE2b-256 checksum How to use checksums |
81dcc3907377724a70305b9acf026cd57ebb7376c4a659f18858121c606595cd
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.13.7 {"installer":{"name":"uv","version":"0.13.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Security for arioso 0.0.53
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.