This document provides comprehensive documentation for the Audial SDK, including detailed information about all functions, parameters, return values, and examples for both the Python API and Command Line Interface (CLI).
- Python API
- Configuration
- Pipelines
- Stem Splitting
- Audio Analysis
- Audio Segmentation
- Analysis Add-ons
- Audio Mastering
- Sample Pack Generation
- MIDI Generation
- Sound-to-Vital Resynthesis (sound2vital)
- Sound-to-Serum 2 Resynthesis (sound2serum)
- Text-to-Vocal Synthesis (text2vox)
- Cold Starts and Service Status
- Error Handling
- Command Line Interface
- Configuration Commands
- Pipeline Commands
- Stem Splitting Commands
- Audio Analysis Commands
- Audio Segmentation Commands
- Analysis Add-on Commands
- Audio Mastering Commands
- Sample Pack Generation Commands
- MIDI Generation Commands
- sound2vital Commands
- sound2serum Commands
- text2vox Commands
- Service Status Command
- Result Data Structure
import audial
# Set API key
audial.config.set_api_key("your_api_key_here")
# Set User ID
audial.config.set_user_id("your_user_id_here")
# Get current API key and User ID
api_key = audial.config.get_api_key()
user_id = audial.config.get_user_id()# Set custom results folder
audial.config.set_results_folder("path/to/custom/folder")
# Get current results folder
results_folder = audial.config.get_results_folder()A pipeline runs several Audial functions as one job: the file is uploaded once and the API feeds each step's output into the next. Both pipelines start with one analysis run, and the analysis and its stems are started together.
| Pipeline | Steps | Outputs |
|---|---|---|
sample-pack |
prepare (the analysis and its stems) -> sample-pack |
outputs.samples |
segmentation |
segmentation (the analysis) -> add-ons (the features, tags and lyrics that featuresToExtract asks for) |
outputs.analysis, outputs.segmentation, outputs.warnings |
outputs.analysis is the URL of the analysis with every add-on result (the merged view, see
Audio Segmentation); outputs.segmentation lists the stored analysis
file. An add-on the caller asked for that could not be made is listed in outputs.warnings,
and the pipeline still completes. Pipelines started before November 2026 report stem-split
as their first step.
audial.pipelines.run(
name: str,
file_path: str,
options: Optional[Dict[str, Any]] = None,
wait: bool = True,
poll_interval: float = 5,
on_progress: Optional[Callable[[Dict[str, Any]], Any]] = None,
api_key: Optional[str] = None
) -> Dict[str, Any]
audial.pipelines.get(pipeline_id: str, api_key: Optional[str] = None) -> Dict[str, Any]
audial.pipelines.cancel(pipeline_id: str, api_key: Optional[str] = None) -> Dict[str, Any]
audial.pipelines.list(limit: int = 20, cursor: Optional[str] = None,
api_key: Optional[str] = None) -> Dict[str, Any]| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
name |
str | Yes | - | "sample-pack" or "segmentation" |
file_path |
str | Yes | - | Path to the local audio file; it is uploaded with the request |
options |
Dict | No | None |
See the options table below |
wait |
bool | No | True |
Poll until the pipeline finishes; False returns the queued status at once |
poll_interval |
float | No | 5 |
Seconds between status polls |
on_progress |
Callable | No | None |
Called with the status dict for the first response and after every poll |
api_key |
str | No | None |
API key to use (uses default if None) |
| Option | Type | Applies to | Description |
|---|---|---|---|
components |
List[str] | sample-pack |
["drums", "bass", "melody"] (the default) or a subset |
genre |
str | both | Genre hint; same list as Audio Segmentation |
bpm |
float | both | Overrides the detected tempo (used for the stems) |
keyString |
str | both | Overrides the detected key, e.g. "A minor" |
featuresToExtract |
List[str] | segmentation |
The add-ons to run after the analysis: mode, energy, loudness, danceability, tatum (audio features), tags, lyrics. Default: all |
Anything you omit gets the API's default, and tempo and key are detected from the file when you do not send them.
The API's pipeline status dictionary:
{
"pipelineId": "...",
"pipeline": "sample-pack",
"state": "queued" | "running" | "completed" | "failed" | "cancelled",
"currentStep": "sample-pack",
"createdAt": ..., "updatedAt": ..., "startedAt": ..., "endedAt": ..., "durationMs": ...,
"steps": [
{"name": "prepare", "state": "completed", "exeId": "...", "durationMs": 41000},
{"name": "sample-pack", "state": "running", "exeId": "...", "subStage": "rendering"}
],
"outputs": {
"samples": ["https://...", ...], # sample-pack
"analysis": "https://.../analysis", # segmentation: the merged view
"segmentation": ["https://...", ...], # segmentation: the stored file
"warnings": ["Lyrics could not be made: ..."] # segmentation, when some add-on failed
},
"original": {"filename": "...", "url": "..."},
"options": {...},
"error": {"step": "...", "code": "...", "message": "..."}
}pipelines.list() returns the page envelope: {"items": [status, ...], "nextCursor": "..."}.
A pipeline that ends failed or cancelled raises AudialError, with the
failing step's name and the worker's message in the text. An account whose free
allowance is used up raises SubscriptionRequiredError (HTTP 402).
import audial
status = audial.pipelines.run(
"sample-pack",
"path/to/audio.mp3",
options={"components": ["drums", "bass"], "genre": "Tech House"},
on_progress=lambda s: print(s["state"], s.get("currentStep")),
)
for url in status["outputs"]["samples"]:
print(url)
# Start one and come back to it later
queued = audial.pipelines.run("segmentation", "path/to/audio.mp3", wait=False)
later = audial.pipelines.get(queued["pipelineId"])
audial.pipelines.cancel(queued["pipelineId"])
# Your recent pipelines, newest first
for item in audial.pipelines.list(limit=10)["items"]:
print(item["pipeline"], item["state"])audial.generate_samples(file) and audial.segment(file, features=[...]) run
these pipelines for you and download the results; call pipelines.run()
directly when you want the output URLs, the per-step timings, or control over
polling.
Split an audio track into its component parts.
audial.stem_split(
file_path: str,
stems: Optional[List[str]] = None,
target_bpm: Optional[float] = None,
target_key: Optional[str] = None,
results_folder: Optional[str] = None,
api_key: Optional[str] = None,
algorithm: str = "primaudio"
) -> Dict[str, Any]| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
file_path |
str | Yes | - | Path to the audio file to process |
stems |
List[str] | No | ["vocals", "drums", "bass", "other"] |
List of stems to extract |
target_bpm |
float | No | None |
Target BPM for tempo adjustment |
target_key |
str | No | None |
Target key for pitch adjustment (e.g., "Cmaj", "Dmin") |
results_folder |
str | No | None |
Folder to save results (uses default if None) |
api_key |
str | No | None |
API key to use (uses default if None) |
algorithm |
str | No | "primaudio" |
Algorithm to use ("primaudio" or "quintessound") |
vocals- Vocal trackdrums- Drum trackbass- Bass trackother- All other instrumentsfull_song_without_vocals- Full mix minus vocalsfull_song_without_drums- Full mix minus drumsfull_song_without_bass- Full mix minus bassfull_song_without_other- Full mix minus other instruments
A dictionary containing:
execution: API response datafiles: Information about downloaded filesfolder: Path to the results folderfiles: Dictionary mapping filenames to local file paths
import audial
# Basic stem splitting
result = audial.stem_split("path/to/audio.mp3")
# Access the paths to the downloaded files
stems_folder = result["files"]["folder"]
vocals_path = result["files"]["files"]["vocals.mp3"]
drums_path = result["files"]["files"]["drums.mp3"]
bass_path = result["files"]["files"]["bass.mp3"]
other_path = result["files"]["files"]["other.mp3"]
# Advanced stem splitting with options
result = audial.stem_split(
"path/to/audio.mp3",
stems=["vocals", "drums", "full_song_without_vocals"],
target_bpm=120,
target_key="Cmaj",
algorithm="primaudio"
)Analyze an audio file to extract metadata like BPM, key, and other characteristics.
audial.analyze(
file_path: str,
results_folder: Optional[str] = None,
api_key: Optional[str] = None
) -> Dict[str, Any]| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
file_path |
str | Yes | - | Path to the audio file to analyze |
results_folder |
str | No | None |
Folder to save results (uses default if None) |
api_key |
str | No | None |
API key to use (uses default if None) |
A dictionary containing:
execution: API response dataanalysis: Analysis results including BPM, key, and other metadatafiles: Information about downloaded filesfolder: Path to the results folderfiles: Dictionary mapping filenames to local file paths
import audial
# Analyze an audio file
analysis = audial.analyze("path/to/audio.mp3")
# Access analysis results
bpm = analysis["analysis"]["bpm"]
key = analysis["analysis"]["key"]
print(f"BPM: {bpm}")
print(f"Key: {key}")Analysis finds your track's sections, tempo and bars in about half a minute. Add audio features, tags, lyrics or a sample pack afterwards, one call each.
Send the mix: you get the sections, phrases and a tempo map. No stems are needed, and nothing
has to be prepared. Without features, segment() is one call
(POST /functions/run/segmentation). It returns the analysis and its analysis_id, which the
add-ons take.
With features, segment() runs the segmentation pipeline, as in 1.5: the API
runs the analysis, then the add-ons those features need, and the result holds them. It takes
longer, because tags and lyrics wait for the analysis's stems.
audial.segment(
file_path: str,
genre: Optional[str] = None,
edm: Optional[bool] = None,
features: Optional[List[str]] = None,
results_folder: Optional[str] = None,
on_progress: Optional[Callable[[Dict[str, Any]], Any]] = None,
expand_beats: bool = True,
*,
api_key: Optional[str] = None,
poll_interval: Optional[float] = None,
max_wait: float = 900,
components: Optional[List[str]] = None, # deprecated, ignored
analysis_type: Optional[str] = None, # deprecated, ignored
) -> Dict[str, Any]| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
file_path |
str | Yes | - | Path to the audio file (the mix) |
genre |
str | No | None |
Genre of the track (see below). It picks dance or song section names when edm is not given |
edm |
bool | No | None |
True: dance section names (INTRO, UP, CHORUS, DOWN, OUTRO). False: song section names (INTRO, VERSE, UP, CHORUS, OUTRO). Default: from the genre, else from the audio |
features |
List[str] | No | None |
Add-ons to run with the analysis (see below). None: the fast analysis only |
results_folder |
str | No | None |
Folder to save results (uses default if None) |
on_progress |
Callable | No | None |
Called with the analysis execution after every status check (with features: the pipeline status). It carries warmup while a machine starts |
expand_beats |
bool | No | True |
Add beat_times and bar_times computed from grid. 2.0 makes this opt-in |
api_key |
str | No | None |
API key to use (uses default if None) |
poll_interval |
float | No | 3 (5 with features) |
Seconds between status checks |
max_wait |
float | No | 900 |
Seconds to wait for the analysis |
components, analysis_type |
No | No longer used. Accepted by name and ignored, with a DeprecationWarning |
The parameters keep their 1.5 order. edm, expand_beats and max_wait are keyword-only.
features names the add-ons to run with the analysis, as 1.5 named them:
mode,energy,loudness,danceability,tatum,key- audio featurestags- tagslyrics- lyrics
"Default", "Afro House", "Tech House", "Bass House", "Blues", "Breakbeat", "Classic Rock", "Country", "Deep House", "Drum N Bass", "Dubstep", "Gospel", "Grime140", "House", "Indie", "Jazz", "Latin", "Metal", "Minimal House", "Pop", "R&B", "Rock", "Techno", "Trance", "Trap", "UK Garage"
A dictionary containing:
analysis_id: The analysis's id, for the add-onsaudio_segmentation: The analysis with every add-on result so far (the merged view,GET /db/{userId}/execution/{exeId}/analysis):format_version(4),duration,bpm,tempo_mode,time_signature,bar1,song_start,mood,modegrid: the tempo mapsections:[{label, start, end, start_bar, bars, phrases, ...}, ...]phrases,lead_insong_analysis: what the add-ons have filled so far:energy,danceability,loudness,mode,mode_confidence,tatum,key(audio features),genre,song_tags(tags),lyrics,lyrics_lines(lyrics).{}before any add-on has runsegment_analysis: one object per section, with the same per-section values ({}until an add-on fills it) and each section'slyricsfirst_vocal_beat_time: when the vocals start (once lyrics exist)beat_times,bar_times: withexpand_beats=True- An analysis from before the tempo map (format 2 or 3) has its own
beat_timesandbar_timesinstead ofgrid
segmentation: The same object, under its 1.5 nameexecution: The analysis execution (withfeatures: the final pipeline status)files:{folder, files}-- the savedanalysis.jsonwarnings: Withfeatures, the add-ons that could not be made (only when there are some)
import audial
song = audial.segment("path/to/audio.mp3", genre="Tech House")
analysis_id = song["analysis_id"]
for section in song["audio_segmentation"]["sections"]:
print(f"{section['start']:7.2f} {section['label']}")
# The add-ons, one call each, any time later
features = audial.audio_features(analysis_id)
tags = audial.tags(analysis_id)
lyrics = audial.lyrics(analysis_id)
# Or everything in one call, as in 1.5 (slower)
full = audial.segment("path/to/audio.mp3", features=["energy", "danceability", "tags", "lyrics"])
print(full["audio_segmentation"]["song_analysis"]["energy"])Cost: an analysis counts as one run. Everything you add to it (features, tags, lyrics, a sample
pack) is included. Calling those on their own, without an analysis, counts as a run each (for
example generate_samples(file_path), which makes its own analysis).
Beats and bars aren't listed one by one. grid describes them: where each constant-tempo piece
starts, its BPM, and its bar and beat. Every beat time is start + k × 60 / bpm. Most tracks
have one piece.
"grid": {
"beats_per_bar": 4, "tolerance_ms": 25, "max_error_ms": 9.2,
"beat_count": 841, "bar_count": 208,
"pieces": [{"start": 0.195, "bpm": 129.0, "bar": -2, "beat": 1, "count": 841}]
}The whole rule: for each piece, beat k (from 0 to count - 1) is at start + k × 60 / bpm
and carries the label (bar, beat); the beat then moves on by one, and after beat
beats_per_bar comes beat 1 of the next bar. Beat times are all the pieces' beats in order,
rounded to 3 decimals. Bar times are the beats with beat == 1 and bar >= 1; bars 0 and below
are the lead-in before bar 1. Every expanded beat is within tolerance_ms of the detected beat.
audial.grid implements it with the standard library only:
| Function | Returns |
|---|---|
audial.grid.expand(grid) |
[(time, bar, beat), ...] for every beat |
audial.grid.beat_times(grid) |
every beat time (len == grid["beat_count"]) |
audial.grid.bar_times(grid) |
the start of every bar from bar 1 (len == grid["bar_count"]) |
audial.grid.beats_of(analysis) |
(beat times, bar times) of an analysis of any format |
beats, bars = audial.grid.beats_of(song["audio_segmentation"])With expand_beats=True (the 1.6 default) segment() adds beat_times and bar_times itself,
so scripts written for older results keep working; the first time, a FutureWarning says that
2.0 makes this opt-in. Pass expand_beats=False and use audial.grid to be ready for 2.0.
Each add-on is one call on an analysis, any time after it: audial.audio_features,
audial.tags, audial.lyrics and audial.generate_samples(analysis_id=...) (Sample Pack
Generation). Each starts its run
(POST /functions/run/{audio-features | audio-tags | lyrics | sample-pack} with
{userId, analysisExeId}), waits for it, and returns its result, which is also saved as
<results folder>/<analysis_id>_analysis/<features|tags|lyrics>.json.
- Prerequisites. Every add-on needs an analysis (
audial.segment()). Tags, lyrics and the sample pack also read the analysis's stems, which are made automatically in the background as soon as the analysis starts; there is nothing to do. Until they are ready the API answers409 STEMS_NOT_READY("This track is still being prepared. Try again in a minute."), and the SDK keeps trying for up towait_sseconds. If making the stems failed, the SDK starts it again once. Audio features need only the mix. - Cost. An analysis counts as one run. Everything you add to it (features, tags, lyrics, a sample pack) is included. Calling those on their own, without an analysis, counts as a run each.
- Repeats. A call while that add-on is running, or after it finished, returns that run's
result instead of starting another;
rerun=Truemakes a new one. - Older analyses. Analyses made by the
segmentationpipeline before 1.6 work too (their id from your history is accepted). One that kept no stems answers409 ADDON_UNAVAILABLE.
audial.audio_features(analysis_id: str, **options) -> Dict[str, Any]
audial.tags(analysis_id: str, **options) -> Dict[str, Any]
audial.lyrics(analysis_id: str, **options) -> Dict[str, Any]All three take the same options:
| Parameter | Type | Default | Description |
|---|---|---|---|
analysis_id |
str | - | The analysis_id that segment() returned |
rerun |
bool | False |
Make a new result even if one exists |
wait_s |
float | 600 |
Seconds to keep trying while the stems are being made (or the analysis is still running) |
max_wait |
float | 900 |
Seconds to wait for the result once the run has started. It keeps running after that; calling again collects it |
poll_interval |
float | 5 |
Seconds between status checks |
results_folder |
str | None |
Folder to save the result in (uses default if None) |
api_key |
str | None |
API key to use (uses default if None) |
on_progress |
Callable | None |
Called with the run's execution record after every check; it carries warmup while a machine starts |
audial.lyrics is also the module of the per-note lyric grammar:
audial.lyrics(analysis_id) calls the add-on, and audial.lyrics.parse_per_note_lyrics and
the rest stay where they were.
Energy, danceability, loudness, mode, key and beat division (tatum), for the song and for each section. Energy and danceability are 0–100% (0 to 1 in the result). Energy reflects loudness, rhythmic activity and low end. Danceability reflects how strong and regular the beat is. Both are measured per section, so a drop reads higher than its breakdown. Loudness is in LUFS and follows the broadcast standard over both channels; it reads 3–6 LU higher than in results from before 1.6.
features = audial.audio_features(analysis_id)
{
"features_version": 1,
"song": {"key": "A min", "key_source": "detected", "loudness": -7.1, "energy": 0.62,
"danceability": 0.71, "mode": "aeolian", "mode_confidence": 0.8, "tatum": "1/16"},
"sections": [{"index": 0, "label": "INTRO", "start": 0.2, "end": 30.0,
"energy": 0.41, "danceability": 0.55, ...}, ...],
"warnings": []
}A value that could not be measured is None.
Genre, moods, instruments and artist tags for the mix and for each of its parts (drums, bass, melody and vocals), plus a written description of the track. The values are exactly what the Audial website shows: use the genres as they are.
tags = audial.tags(analysis_id)
{
"genre": ["UK Garage", "Speed Garage"],
"song_tags": {
"full": {"moods": [...], "instruments": [...], "artist_tags": [...]},
"drums": {"moods": [...], "instruments": [...], "silent": False},
"bass": {"moods": [...], "instruments": [...], "silent": False},
"melody": {"moods": [...], "instruments": [...], "silent": False},
"vocals": {"moods": [...], "instruments": [...], "silent": False}
},
"description": "A driving UK garage cut ...", # "" when none was made
"warnings": []
}Every list is present, empty when nothing was found. A part whose stem is silent has
"silent": True and empty lists (for vocals, the track has no vocals). An analysis made before
the drums and vocals were tagged has the first three parts only and no description (""). The same
values are in song_analysis of the analysis (genre, song_tags, description).
The lyrics with a start and end for every word, in seconds on the track's timeline: ready for a karaoke-style highlight.
lyrics = audial.lyrics(analysis_id)
{
"lyrics": "hello there ...",
"is_instrumental": False,
"lines": [
{"start": 12.34, "end": 13.10,
"words": [["hello", 12.34, 12.71], ["there", 12.80, 13.10]]},
...
],
"segments": [{"text": "hello there", "start": 12.34, "end": 13.10}, ...],
"section_lyrics": ["", "hello there ...", ...], # one per section of the analysis
"first_vocal_beat_time": 12.34, # None without vocals
"warnings": []
}
for line in lyrics["lines"]:
for word, start, end in line["words"]:
print(f"{start:7.2f} {word}")An instrumental has is_instrumental True and no lines ("No vocals in this track."). After
lyrics have run, the merged view (segment()'s result) also has them as
song_analysis.lyrics_lines, each section's lyrics, and first_vocal_beat_time. See
examples/lyrics_lines.py.
Apply professional mastering to an audio file.
audial.master(
file_path: str,
reference_file: Optional[str] = None,
results_folder: Optional[str] = None,
api_key: Optional[str] = None
) -> Dict[str, Any]| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
file_path |
str | Yes | - | Path to the audio file to master |
reference_file |
str | No | None |
Path to a reference file to match sound characteristics |
results_folder |
str | No | None |
Folder to save results (uses default if None) |
api_key |
str | No | None |
API key to use (uses default if None) |
A dictionary containing:
execution: API response datafiles: Information about downloaded filesfolder: Path to the results folderfiles: Dictionary mapping filenames to local file paths
import audial
# Basic mastering
mastered = audial.master("path/to/audio.mp3")
# Mastering with reference track
mastered = audial.master(
"path/to/audio.mp3",
reference_file="path/to/reference.mp3"
)
# Get the path to the mastered file
master_file = next(iter(mastered["files"]["files"].values()))Generate a sample pack from an audio file, or from an analysis you already have.
- From a file (
file_path): this runs thesample-packpipeline. The analysis and the stems start together (stepprepare), then the pack is built from them (stepsample-pack), in a single API call. Tempo and key are detected automatically.executionin the result is the pipeline status, so every step and its timing is visible there;audial.pipelines.run("sample-pack", ...)is the same job without the downloads. It counts as one run. - From an analysis (
analysis_id): the pack is built from that analysis's stems and sections, with no new analysis or stem split. It is an add-on, included with the analysis. The stems are made in the background as soon as the analysis starts; until they are ready the API answers409 STEMS_NOT_READYand the SDK keeps trying for up towait_sseconds.
audial.generate_samples(
file_path: Optional[str] = None,
job_type: Optional[str] = None,
components: Optional[List[str]] = None,
genre: Optional[str] = None,
results_folder: Optional[str] = None,
api_key: Optional[str] = None,
on_progress: Optional[Callable[[Dict[str, Any]], Any]] = None,
poll_interval: float = 5,
analysis_id: Optional[str] = None,
wait_s: float = 600,
max_wait: float = 900
) -> Dict[str, Any]| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
file_path |
str | One of file_path, analysis_id |
- | Path to the audio file |
job_type |
str | No | "sample_pack" |
Type of sample pack job to run |
components |
List[str] | No | ["drums", "bass", "melody"] |
Components to include in the sample pack |
genre |
str | No | "Default" |
Genre of the track (not used with analysis_id) |
results_folder |
str | No | None |
Folder to save results (uses default if None) |
api_key |
str | No | None |
API key to use (uses default if None) |
on_progress |
Callable | No | None |
Called with the pipeline status after every poll (with analysis_id: the sample-pack run's execution record) |
poll_interval |
float | No | 5 |
Seconds between status polls |
analysis_id |
str | One of file_path, analysis_id |
None |
An analysis of yours: the analysis_id that segment() returned |
wait_s |
float | No | 600 |
With analysis_id: seconds to keep trying while the stems are being made |
max_wait |
float | No | 900 |
With analysis_id: seconds to wait for the pack once it has started |
drums- Drum samplesbass- Bass samplesmelody- Melodic samples
Same as Audio Segmentation.
A dictionary containing:
execution: The final pipeline status (steps, outputs, timings); withanalysis_id, the analysis recordfiles: Information about downloaded filesfolder: Path to the results folderfiles: Dictionary mapping filenames to local file paths
analysis_id: Withanalysis_id, the analysis's idcomponents: Withanalysis_id, what each part gave:{"drums": {"status": "ok" | "empty" | "failed" | "skipped", ...}, ...}
import audial
# Basic sample pack generation
samples = audial.generate_samples("path/to/audio.mp3")
# Advanced sample pack generation with options
samples = audial.generate_samples(
"path/to/audio.mp3",
job_type="sample_pack",
components=["drums", "bass", "melody"],
genre="Tech House"
)
# Access the sample pack folder
samples_folder = samples["files"]["folder"]
# List all downloaded samples
for sample_name, sample_path in samples["files"]["files"].items():
print(f"{sample_name}: {sample_path}")
# From an analysis: its stems and sections, included with it
song = audial.segment("path/to/audio.mp3", genre="Tech House")
pack = audial.generate_samples(analysis_id=song["analysis_id"], components=["drums", "bass"])
print(pack["components"])Convert audio to MIDI data.
audial.generate_midi(
file_path: Union[str, List[str]],
bpm: Optional[float] = None,
results_folder: Optional[str] = None,
api_key: Optional[str] = None
) -> Dict[str, Any]| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
file_path |
str or List[str] | Yes | - | Path to one or more audio files |
bpm |
float | No | None |
Override BPM for the MIDI generation |
results_folder |
str | No | None |
Folder to save results (uses default if None) |
api_key |
str | No | None |
API key to use (uses default if None) |
A dictionary containing:
execution: API response datafiles: Information about downloaded filesfolder: Path to the results folderfiles: Dictionary mapping filenames to local file paths
import audial
# Generate MIDI from a single file
midi = audial.generate_midi("path/to/audio.mp3", bpm=120)
# Generate MIDI from multiple files
midi = audial.generate_midi(
["path/to/file1.mp3", "path/to/file2.mp3"],
bpm=140
)
# Access the MIDI files
for midi_file, file_path in midi["files"]["files"].items():
print(f"{midi_file}: {file_path}")Synthesize a Vital synth preset that reproduces the timbre of one isolated sound. This is a paid function -- it requires an active Audial subscription in addition to a valid API key (see Error Handling).
Input: One isolated sound: a single note, chord stab or hit, ideally 1-4 seconds and dry, 20 seconds at most. Not a loop, melody, drum pattern or anything with several notes in sequence: those produce a poor preset even under 20 seconds. To use a loop, trim it to one note first.
audial.sound2vital(
file_path: str,
results_folder: Optional[str] = None,
api_key: Optional[str] = None,
max_wait: float = 360,
poll_interval: float = 5,
on_progress: Optional[Callable[[Dict[str, Any]], Any]] = None
) -> Dict[str, Any]| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
file_path |
str | Yes | - | Path to the input audio file. Must be 20 seconds or shorter |
results_folder |
str | No | None |
Folder to save results (uses default if None) |
api_key |
str | No | None |
API key to use (uses default if None) |
max_wait |
float | No | 360 |
Maximum seconds to wait for completion (jobs typically take 60-250s) |
poll_interval |
float | No | 5 |
Seconds between execution status polls |
on_progress |
callable | No | None |
Called with the execution record after every poll -- see Cold Starts and Service Status |
A dictionary containing:
execution: API response datafiles: Information about downloaded filesfolder: Path to the results folderfiles: Dictionary mapping filenames to local file paths (the.vitalpreset plus any generated render/keyboard/report files)
preset: Local path to the downloaded.vitalpreset, if the job produced onescores:generation_metadata.scores--huang_similarity,at_threshold,threshold,model-- if present.at_threshold: Falsemeans a weaker match, usually because the input was not one isolated soundreport:generation_metadata.report, if presentwarnings:generation_metadata.warningslist, if present. Includes a note when the input sounds like several notes in a row
import audial
result = audial.sound2vital("path/to/clip.wav")
print(f"Preset: {result['preset']}")
print(f"Similarity score: {result['scores']['huang_similarity']}")Synthesize a Serum 2 preset that reproduces
the timbre of one isolated sound. No Audial plugin is needed for this one -- the output
is a .SerumPreset file opened directly in Xfer's Serum 2. This is a paid function -- it
requires an active Audial subscription in addition to a valid API key (see Error
Handling).
Input: One isolated sound: a single note, chord stab or hit, ideally 1-4 seconds and dry, 20 seconds at most. Not a loop, melody, drum pattern or anything with several notes in sequence: those produce a poor preset even under 20 seconds. To use a loop, trim it to one note first.
Serum runs take about 2.5 minutes, plus up to another 2.5 minutes if a worker has to
cold-start -- max_wait defaults higher than sound2vital's to cover that.
audial.sound2serum(
file_path: str,
results_folder: Optional[str] = None,
api_key: Optional[str] = None,
max_wait: float = 480,
poll_interval: float = 5,
on_progress: Optional[Callable[[Dict[str, Any]], Any]] = None
) -> Dict[str, Any]| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
file_path |
str | Yes | - | Path to the input audio file. Must be 20 seconds or shorter |
results_folder |
str | No | None |
Folder to save results (uses default if None) |
api_key |
str | No | None |
API key to use (uses default if None) |
max_wait |
float | No | 480 |
Maximum seconds to wait for completion (Serum runs take ~2.5 min, plus up to ~2.5 min for a cold start) |
poll_interval |
float | No | 5 |
Seconds between execution status polls |
on_progress |
callable | No | None |
Called with the execution record after every poll -- see Cold Starts and Service Status |
A dictionary containing:
execution: API response datafiles: Information about downloaded filesfolder: Path to the results folderfiles: Dictionary mapping filenames to local file paths (the.SerumPresetpreset plus any generated render/keyboard/report files)
preset: Local path to the downloaded.SerumPresetpreset, if the job produced one. Saved as<source file stem>.SerumPreset-- Serum shows the file name as the preset name, so naming it after your sample is what shows up inside Serumscores:generation_metadata.scores--huang_similarity,at_threshold,threshold,model-- if present.at_threshold: Falsemeans a weaker match, usually because the input was not one isolated soundreport:generation_metadata.report, if presentwarnings:generation_metadata.warningslist, if present. Includes a note when the input sounds like several notes in a row
import audial
result = audial.sound2serum("path/to/clip.wav")
print(f"Preset: {result['preset']}")
print(f"Similarity score: {result['scores']['huang_similarity']}")Synthesize a sung vocal in the timbre of a short reference voice clip, following a melody (MIDI or audio) and lyrics. This is a paid function -- it requires an active Audial subscription in addition to a valid API key (see Error Handling).
Exactly one of midi_file / melody_audio_file must be given -- the underlying worker
needs one of the two to drive the melody.
text2vox sings one note at a time: the MIDI must be a single melody line, not chords or harmony. Two notes that start together (a chord), or a note that starts more than 50 ms before the previous one ends, is refused before anything runs (HTTP 400, MELODY_INVALID, or LYRICS_INVALID with per_note), naming the note number and its time; nothing runs and nothing is charged. Overlaps of 50 ms or less are trimmed automatically. With per_note, a note with no length (usually one stacked on another note of the same pitch) or a note that never ends is refused too.
audial.text2vox(
reference_file: str,
lyrics: str,
midi_file: Optional[str] = None,
melody_audio_file: Optional[str] = None,
word_timestamps_file: Optional[str] = None,
lyrics_mode: str = "auto",
reference_text: Optional[str] = None,
cfg_strength: Optional[float] = None,
nfe_steps: Optional[int] = None,
pitch_shift: Optional[float] = None,
strict_pitch: Optional[bool] = None,
bend_smoothing_ms: Optional[float] = None,
no_pitch_bends: Optional[bool] = None,
leading_silence_s: Optional[float] = None,
seed: Optional[int] = None,
results_folder: Optional[str] = None,
api_key: Optional[str] = None,
max_wait: float = 360,
poll_interval: float = 5,
on_progress: Optional[Callable[[Dict[str, Any]], Any]] = None
) -> Dict[str, Any]| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
reference_file |
str | Yes | - | Path to a short (5-10s) reference voice clip -- the voice to sing in |
lyrics |
str | Yes | - | The lyrics to sing. In per_note mode this is pipe-delimited, one token per MIDI note -- see Per-note lyrics |
midi_file |
str | One of midi_file/melody_audio_file | None |
Path to a MIDI file driving the melody: one note at a time, a single melody line, not chords or harmony |
melody_audio_file |
str | One of midi_file/melody_audio_file | None |
Path to override melody audio (skips strict-pitch synthesis) |
word_timestamps_file |
str | No | None |
Path to a word-timestamps JSON, used by auto-align |
lyrics_mode |
str | No | "auto" |
"auto" (word count matches MIDI notes, auto-aligns via word_timestamps), "per_note" (pipe-delimited, one token per note -- see Per-note lyrics), or "1to1" (passed straight through) |
reference_text |
str | No | None |
What is said in the reference clip |
cfg_strength |
float | No | None |
Worker synthesis option |
nfe_steps |
int | No | None |
Worker synthesis option |
pitch_shift |
float | No | None |
Worker synthesis option |
strict_pitch |
bool | No | None |
Worker synthesis option |
bend_smoothing_ms |
float | No | None |
Worker synthesis option |
no_pitch_bends |
bool | No | None |
Worker synthesis option |
leading_silence_s |
float | No | None |
Worker synthesis option |
seed |
int | No | None |
Random seed for reproducibility |
results_folder |
str | No | None |
Folder to save results (uses default if None) |
api_key |
str | No | None |
API key to use (uses default if None) |
max_wait |
float | No | 360 |
Maximum seconds to wait for completion |
poll_interval |
float | No | 5 |
Seconds between execution status polls |
on_progress |
callable | No | None |
Called with the execution record after every poll -- see Cold Starts and Service Status |
A dictionary containing:
execution: API response datafiles: Information about downloaded filesfolder: Path to the results folderfiles: Dictionary mapping filenames to local file paths (the rendered wav plus any MIDI actually used, if the worker returned one)
metadata:generation_metadatadict (duration_s,sample_rate), if presentwarnings:generation_metadata.warningslist, if present
import audial
# Driven by a MIDI file
result = audial.text2vox(
reference_file="path/to/voice_clip.wav",
lyrics="la la la la",
midi_file="path/to/melody.mid",
)
# Driven by melody audio instead
result = audial.text2vox(
reference_file="path/to/voice_clip.wav",
lyrics="la la la la",
melody_audio_file="path/to/melody.wav",
lyrics_mode="per_note",
)
for name, path in result["files"]["files"].items():
print(f"{name}: {path}")lyrics_mode="per_note" gives you a syllable per MIDI note. The lyrics are pipe-delimited,
one token per note, and there is exactly one concept beyond "a syllable on a note": a
hold, which means "keep singing the previous syllable through this note".
| Token | Meaning |
|---|---|
grace |
Sung on this note |
- |
Hold: continue the previous syllable through this note (the documented form) |
+ |
Hold as well (a Synthesizer V habit) |
| empty | Hold as well -- what a double pipe a||b produces |
A token may be a whole word spread over several notes:
import audial
result = audial.text2vox(
reference_file="voice_clip.wav",
midi_file="melody.mid", # 9 notes
lyrics="amazing|-|-|grace|-|how|sweet|the|sound",
lyrics_mode="per_note",
)Here "amazing" is sung across notes 1-3 and "grace" across notes 4-5; the held notes are merged into their predecessor before synthesis and their pitch movement is kept as a bend, so the sung line still follows the drawn melody and the returned MIDI shows the merged notes.
There is no rest token. A note that should be silent should not be in the MIDI at all.
Two rules apply:
- The token count must equal the MIDI note count.
- The first token must be a syllable -- a hold continues something, and there is nothing before note 1.
Rule 2 (and an empty lyric string) is checked by the SDK before anything is uploaded, so a typo costs no uploads and creates no execution:
from audial.api.exceptions import AudialValidationError
try:
audial.text2vox(..., lyrics="-|grace", lyrics_mode="per_note")
except AudialValidationError as e:
print(e) # note 1 has no syllable; the first note needs one
print(e.position) # 1 -- the 1-based note the message is aboutRule 1 needs the MIDI, so it is the API's; it comes back as the same exception, raised
from the API's 400 {"code": "LYRICS_INVALID", "position", "message"} response:
9 tokens for 10 notes; the first unmatched note starts at 2.4 s
audial.text2vox_tokens() answers "how many notes does this lyric string need?" without
running anything, and raises the same error for input that cannot be sung:
tokens = audial.text2vox_tokens("amazing|-|-|grace|-|how|sweet|the|sound")
len(tokens) # 9 -- notes required
[t.text for t in tokens if not t.hold] # ['amazing', 'grace', 'how', 'sweet', 'the', 'sound']
tokens[1] # Token(text='', hold=True)auto and 1to1 are unchanged, and every per-note string that worked before renders
identically.
Audial's GPU workers scale to zero. The first request after an idle period has to start a worker and load the model before any audio is processed, which adds a few minutes to that one job; every run after it is fast. Without a word about it, a cold start looks exactly like a hung job.
The API decides warm vs cold before it dispatches and writes the phase onto the execution (and onto each pipeline step), so every client reads the same field:
"warmup": {
"state": "cold" | "initializing" | "working" | "done",
"expectedColdStartMs": 180000, # this endpoint's recent cold-start p50
"expectedRunMs": 42000,
"delayMs": 174000 # state "done": what the wait actually cost
}Every function that polls -- text2vox, sound2vital, sound2serum, generate_music,
stem_split, master, generate_midi, analyze, segment, the add-ons audio_features,
tags and lyrics, and generate_samples -- takes an optional on_progress callback that receives each status as
it arrives. audial.warmup turns one into the sentence the CLI, the website and the MCP
server all show, and WarmupTracker reduces the stream to one line per change:
import audial
tracker = audial.warmup.WarmupTracker()
def report(status):
for line in tracker.changes(status):
print(line)
audial.sound2vital("kick.wav", on_progress=report)
# Warming up the machine - the first request takes a few minutes longer than
# usual (about 3 min); every run after this is faster
# Working on your job...audial.status() wraps GET /functions/status, which can be called before a job exists
-- the only way to explain the wait before someone sits through it:
doc = audial.status("text2vox")
# {'items': [{'function': 'text2vox', 'warm': False, 'queued': 0,
# 'expectedColdStartMs': 180000, 'expectedRunMs': 42000}]}
if audial.warmup.is_cold(doc, "text2vox"):
print(audial.warmup.cold_start_message(
audial.warmup.find_function(doc, "text2vox").get("expectedColdStartMs")
))status() accepts either an SDK name ("generate_samples") or the API's own name
("sample-pack"), and omitting it reports every function.
The analysis add-ons run on machines of their own (audio-features, audio-tags, lyrics and
sample-pack), so the first add-on after a quiet period can wait for a machine to start even
when the analysis was quick ("Starting up — this can take a minute"). Their on_progress
receives the add-on run's execution record, with its warmup, and audial.status("tags")
(or "audio_features", "lyrics") asks before you call. Tags, lyrics and the sample pack can
also wait for the analysis's stems, which is reported as "Preparing the track…". The call is cached server-side
and costs no rate-limit allowance. The CLI does this automatically before every job (see
Service Status Command).
The SDK provides custom exception classes for better error handling:
from audial.api.exceptions import (
AudialError,
AudialAuthError,
AudialAPIError,
AudialValidationError,
SubscriptionRequiredError,
)
try:
result = audial.stem_split("path/to/audio.mp3")
except AudialValidationError as e:
print(f"Unusable input: {e} (position {e.position})")
# Input rejected before (or instead of) running anything -- today this is
# per-note lyrics; `position` is the 1-based note the message is about
except SubscriptionRequiredError as e:
print(f"Subscription required: {e}")
# sound2vital, sound2serum and text2vox require an active Audial subscription
# (HTTP 402, code SUBSCRIPTION_REQUIRED) in addition to a valid API key
except AudialAuthError as e:
print(f"Authentication error: {e}")
# Handle authentication issues
except AudialAPIError as e:
print(f"API error: {e}")
# Handle API-specific issues
except AudialError as e:
print(f"General error: {e}")
# Handle other errorsThe analysis add-ons (audio_features, tags, lyrics, generate_samples(analysis_id=...))
raise AudialAPIError with status_code 409 and code set when the API refuses them:
code |
Message | When |
|---|---|---|
STEMS_NOT_READY |
"This track is still being prepared. Try again in a minute." | Tags, lyrics or a sample pack whose stems were still being made after wait_s seconds. The SDK retries this answer by itself until then. When the stems could not be made at all (the SDK restarts them once), the message starts "We couldn't prepare this track." |
ADDON_UNAVAILABLE |
"This result can't be added to this analysis." | The add-on's inputs can't be found, for example an older analysis that kept no stems. While the analysis itself is still running, the SDK waits instead |
try:
lyrics = audial.lyrics(analysis_id, wait_s=120)
except AudialAPIError as e:
if e.code == "STEMS_NOT_READY":
print("Still preparing the track; try again in a minute")
elif e.code == "ADDON_UNAVAILABLE":
print("This analysis can't have lyrics")
else:
raiseEvery AudialAPIError has status_code (the HTTP status, or None for a network error) and
code (the API's error code, when it sent one).
Note: SubscriptionRequiredError is a subclass of AudialAPIError, so an except AudialAPIError clause also catches it -- catch SubscriptionRequiredError first if you
need to handle it differently (e.g. prompting the user to subscribe).
AudialValidationError is a subclass of AudialError and carries a position; see
Per-note lyrics.
The Audial SDK provides a command-line interface for all its functions.
audial config --showaudial config --api-key your_api_key_hereaudial config --user-id your_user_id_hereaudial config --results-folder path/to/results/folderRun a whole pipeline in one call, printing a line per step change: sample-pack (the
analysis and its stems, then the pack) or segmentation (the analysis, then its add-ons).
audial pipeline sample-pack path/to/audio.mp3audial pipeline segmentation path/to/audio.mp3audial pipeline sample-pack path/to/audio.mp3 \
--genre "Tech House" \
--components drums bass melody \
--bpm 128 \
--key "A minor"| Flag | Description |
|---|---|
--genre |
Genre hint |
--components |
Components to process, space separated |
--bpm |
Override the detected tempo |
--key |
Override the detected key |
--no-wait |
Start the pipeline and print its id without waiting |
--poll-interval |
Seconds between status polls (default 5) |
--json |
Print the pipeline status as JSON instead of a summary |
--api-key |
API key to use |
audial pipeline segmentation path/to/audio.mp3 --jsonPrints only the pipeline status document, for piping into other tools.
audial stem-split path/to/audio.mp3audial stem-split path/to/audio.mp3 --stems vocals,drums,bass,otheraudial stem-split path/to/audio.mp3 --stems full_song_without_vocals,full_song_without_drumsaudial stem-split path/to/audio.mp3 --target-bpm 120audial stem-split path/to/audio.mp3 --target-key Cmajaudial stem-split path/to/audio.mp3 --algorithm primaudioaudial stem-split path/to/audio.mp3 --algorithm quintessoundaudial stem-split path/to/audio.mp3 --results-folder path/to/custom/folderaudial stem-split path/to/audio.mp3 --api-key your_custom_api_keyaudial analyze path/to/audio.mp3audial analyze path/to/audio.mp3 --results-folder path/to/custom/folderaudial analyze path/to/audio.mp3 --api-key your_custom_api_keyFind a track's sections, tempo and bars in about half a minute. It prints the analysis id, which the add-on commands take.
audial segment path/to/audio.mp3audial segment path/to/audio.mp3 --genre "Tech House"audial segment path/to/audio.mp3 --edm # INTRO, UP, CHORUS, DOWN, OUTRO
audial segment path/to/audio.mp3 --no-edm # INTRO, VERSE, UP, CHORUS, OUTROaudial segment path/to/audio.mp3 --features energy loudness danceability tags lyricsRuns the segmentation pipeline, which waits for the add-ons too, so it takes longer.
audial segment path/to/audio.mp3 --jsonaudial segment path/to/audio.mp3 --results-folder path/to/custom/folderaudial segment path/to/audio.mp3 --api-key your_custom_api_keyfeatures, tags and lyrics take an analysis id (from audial segment) or an audio file;
a file is analysed first. Each waits for its result and prints it. They are included with the
analysis.
audial features <analysis_id> # energy, danceability, loudness, mode, key, beat division
audial tags <analysis_id> # genre, moods, instruments, artist tags
audial lyrics <analysis_id> # timed lines
audial lyrics path/to/audio.mp3 --genre "Pop"| Flag | Description |
|---|---|
--genre |
Genre of the track, when a file is analysed first |
--rerun |
Make a new result even if one exists |
--wait-s |
Seconds to keep trying while the track is being prepared (default 600) |
--json |
Print the result as JSON (progress goes to stderr) |
--results-folder |
Folder to save results |
--api-key |
API key to use |
audial master path/to/audio.mp3 --reference path/to/reference.mp3Note: The reference file is required for the CLI interface.
audial master path/to/audio.mp3 --reference path/to/reference.mp3 --results-folder path/to/custom/folderaudial master path/to/audio.mp3 --reference path/to/reference.mp3 --api-key your_custom_api_keyaudial generate-samples path/to/audio.mp3audial generate-samples path/to/audio.mp3 --components drums,bass,melodyaudial generate-samples path/to/audio.mp3 --genre "Tech House"audial generate-samples --analysis-id <analysis_id> --components drums bassaudial generate-samples path/to/audio.mp3 --job-type sample_packaudial generate-samples path/to/audio.mp3 --results-folder path/to/custom/folderaudial generate-samples path/to/audio.mp3 --api-key your_custom_api_keyaudial generate-midi path/to/audio.mp3audial generate-midi path/to/file1.mp3 path/to/file2.mp3 path/to/file3.mp3audial generate-midi path/to/audio.mp3 --bpm 120audial generate-midi path/to/audio.mp3 --results-folder path/to/custom/folderaudial generate-midi path/to/audio.mp3 --api-key your_custom_api_keyRequires an active Audial subscription.
audial sound2vital path/to/clip.wavaudial sound2vital path/to/clip.wav --results-folder path/to/custom/folderaudial sound2vital path/to/clip.wav --api-key your_custom_api_keyRequires an active Audial subscription. No Audial plugin is needed -- the output is a
.SerumPreset file opened directly in Xfer's Serum 2. Serum runs take about 2.5 minutes,
plus up to another 2.5 minutes if a worker has to cold-start.
audial sound2serum path/to/clip.wavaudial sound2serum path/to/clip.wav --results-folder path/to/custom/folderaudial sound2serum path/to/clip.wav --api-key your_custom_api_keyRequires an active Audial subscription. Exactly one of --midi / --melody-audio must be
given. The MIDI must be one note at a time: a single melody line, not chords or harmony.
audial text2vox path/to/voice_clip.wav "la la la la" --midi path/to/melody.midaudial text2vox path/to/voice_clip.wav "la la la la" --melody-audio path/to/melody.wavaudial text2vox path/to/voice_clip.wav "la|la|la|la" --midi path/to/melody.mid --lyrics-mode per_noteOne token per MIDI note; - (or +, or an empty token) holds the previous syllable
through that note, so a word can span notes. See Per-note lyrics.
audial text2vox voice_clip.wav "amazing|-|-|grace|-|how|sweet|the|sound" \
--midi melody.mid --lyrics-mode per_noteA lyric string that cannot be sung is refused before anything is uploaded:
Error: note 1 has no syllable; the first note needs one
audial text2vox path/to/voice_clip.wav "la la la la" --midi path/to/melody.mid --results-folder path/to/custom/folderaudial text2vox path/to/voice_clip.wav "la la la la" --midi path/to/melody.mid --api-key your_custom_api_keyWhich functions have a worker awake right now (GET /functions/status):
audial statusService status:
text2vox: warming up
Warming up the machine - the first request takes a few minutes longer than usual (about 3 min); every run after this is faster
sample-pack: ready
stem-splitter: ready, 2 queued
One function, or the raw document:
audial status --function text2vox
audial status --jsonEvery command that runs a job makes this check itself before it submits, and then prints each warm-up phase as the job reports it, so a cold start is explained rather than looking like a hang. See Cold Starts and Service Status.
All functions return a consistent result structure:
{
"execution": {
# Raw API response data
"exeId": "execution-id",
"state": "completed",
"original": {
"bpm": 120,
"key": "Cmaj",
"filename": "original.mp3",
"url": "https://storage.url/path/to/file.mp3"
},
# Function-specific data (e.g., "stem", "midi", "master", etc.)
"stem": {
"vocalsmp3": {
"bpm": 120,
"key": "Cmaj",
"filename": "vocals.mp3",
"url": "https://storage.url/path/to/vocals.mp3"
},
# Other stems...
},
# Other execution data...
},
# For some functions, function-specific data may be included here
"analysis": {
"bpm": 120,
"key": "Cmaj",
"execution_id": "execution-id"
},
"segmentation": {
# Segmentation data
},
"files": {
"folder": "./audial_results/execution-id_function-type",
"files": {
"filename1.mp3": "./audial_results/execution-id_function-type/filename1.mp3",
"filename2.mp3": "./audial_results/execution-id_function-type/filename2.mp3",
# Other downloaded files...
}
}
}The structure may vary slightly depending on the function, but will always include:
execution: The raw API response datafiles: Information about the downloaded filesfolder: Path to the results folderfiles: Dictionary mapping filenames to local file paths
Some functions may include additional fields with function-specific data, such as analysis for the analyze function, and analysis_id and audio_segmentation for segment. The analysis add-ons (audio_features, tags, lyrics) return their result itself (see Analysis Add-ons).