arioso

Arioso - Unified facade for AI music generation platforms.

Usage:

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")

arioso.AUDIO_INPUT_AFFORDANCES = ('audio_input', 'melody', 'reference_audio'): Affordances that carry caller-supplied input audio (used by 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: Song) → list[Song][source]

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 – A Song object (typically with status=’pending’).
Returns:: List of updated Song objects with current status and audio URLs.

Example:

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: str = '', *, platform: str = 'stable_audio', strength: float = None, as_: str = 'auto', **kwargs) → Song[source]

Transform existing audio into AI-enhanced audio (pipeline stage 3->4).

Progressive-disclosure sugar over 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, AudioResult, bytes, a file path, an (array, sample_rate) pair, or a NumPy waveform (normalized by arioso._audio.to_audio_ref).
prompt – Optional text guiding the transformation.
platform – An audio-capable platform (default 'stable_audio'); verify with supports_audio_input().
strength – 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 – Which affordance to route audio into – 'auto' (default; picks audio_input > melody > reference_audio) or an explicit affordance name from AUDIO_INPUT_AFFORDANCES.
**kwargs – Further unified affordance parameters (duration, seed, …).

Returns:

A Song with the enhanced audio.

Example:

rendered = ...  # a Song from a score2audio render
better = arioso.enhance(rendered, "warm analog studio band")

arioso.fetch_audio(song: Song) → Song[source]

Download the audio bytes for a Song that has an audio_url.

Parameters:: song – A Song with a populated audio_url (status=’complete’).
Returns:: A new Song with audio_bytes populated.

Example:

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: str, *, platform: str = 'musicgen', **kwargs) → Song[source]

Generate music using the specified platform.

Parameters:

prompt – Text description of desired music.
platform – Name of the generation platform (default: ‘musicgen’).
**kwargs – Parameters using unified affordance names. See arioso.base.AFFORDANCES for the full list.

Returns:

A Song object containing the generated audio and metadata.

Example:

song = generate("upbeat jazz piano", platform="musicgen", duration=10)

arioso.generate_many(prompt: str, *, platform: str = 'musicgen', **kwargs) → list[Song][source]

Generate music, returning all results (some platforms return multiple).

Same interface as generate() but always returns a list.

arioso.get_platform_info(name: str) → dict[source]

Get configuration info for a platform.

Parameters:: name – Platform identifier.
Returns:: The platform’s PLATFORM_CONFIG dict.

arioso.list_platforms() → list[str][source]: Return names of all available platforms.

arioso.supports_audio_input(platform: str) → bool[source]

Whether platform can condition on caller-supplied input audio.

Returns True if the platform declares any of AUDIO_INPUT_AFFORDANCES (audio_input / melody / reference_audio) in its config’s supported_affordances.

Example:

arioso.supports_audio_input("stable_audio")  # True
arioso.supports_audio_input("mubert")        # False