Skip to main content

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, 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.

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

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, 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. Tries audiocraft first, falls back to HuggingFace transformers.

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) points elsewhere. Magenta RealTime and ACE-Step 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

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:

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:

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_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.<platform>.generate alike).
  • 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.43

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for arioso 0.0.43
File Size Uploaded Provenance Actions
arioso-0.0.43.tar.gz 138.5 kB Without provenance Details for arioso-0.0.43.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for arioso 0.0.43
File Interpreter ABI Platform Actions
arioso-0.0.43-py3-none-any.whl Python 3 none any Details for arioso-0.0.43-py3-none-any.whl

Total release size: 308.2 kB

Release files / arioso-0.0.43.tar.gz

Download URL arioso-0.0.43.tar.gz
Size 138.5 kB
Tags Source
SHA-256 checksum
How to use checksums
2fc1c25ca282f179032846c32dc7da468ed75f940d16d1ef1dc283ea82975ad8
BLAKE2b-256 checksum
How to use checksums
e74746c4770f17e74eaafcabe3bb9a1921859598da9360d04d6001a500f57698
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.43-py3-none-any.whl

Download URL arioso-0.0.43-py3-none-any.whl
Size 169.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
afd6635913502d9dfa6cdf80e66bb796f193f0ad0e8ea3cab3efba70338d4317
BLAKE2b-256 checksum
How to use checksums
ae38cd3959530adf8c7962883576e7ab1121344f980446fb4d145c44367ef115
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.43

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.

Release history Release notifications | RSS feed

This release

0.0.43 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page