# RoEx Tonn API

The RoEx Tonn API provides endpoints for audio mastering, mixing, stem separation, recombine and mastering, post-production, and analysis. Submit tracks for processing and retrieve previews or final results via download URLs. Stem separation (/separate) splits a stereo track into stems — by default vocals, drums, bass, and other; or, with separationMode "vocals_instrumental", a vocals stem plus a single instrumental backing stem; recombine (/recombine) mixes a vocal against a backing track or licensed beat using a fixed automatic recipe (with an optional +/-6dB vocal trim) and masters the result to a LOW/MEDIUM/HIGH loudness preset. Post-production endpoints support dialogue enhancement, delivery format mastering, loudness compliance checks, sidechain ducking, full multi-track mixing, and ADR-to-location matching. The API supports different musical styles, loudness presets, delivery formats, and sample rates.

Base URL: https://tonn.roexaudio.com
Authentication: X-API-Key request header (preferred), or a "key" query parameter

## Endpoints

POST /mixpreview
  Creates a multitrack mix task preview. Doesn't consume any credits.
  - trackData: array (required) — An array containing parameters for each track to be mixed. Maximum of 32 tracks allowed; each track must be no longer than 8 mins.
  - musicalStyle: string (required) — The musical style for the mix.
  - returnStems: boolean — Whether to return URLs for the processed stems.
  - sampleRate: integer — Desired sample rate. Use 44100 for 44.1kHz (16-bit) or 48000 for 48kHz (24-bit).
  - webhookURL: string — Optional URL to receive webhook notifications with status updates for the mix task.

POST /retrievepreviewmix
  Retrieves the URL for the preview mix. Retrieving mix FX settings consumes credits.
  - multitrackTaskId: string (required) — The ID of the multitrack mix task.
  - retrieveFXSettings: boolean (required) — Flag indicating whether to retrieve FX settings (charges may apply).

POST /retrievefinalmix
  Retrieves the URL for the final mix.
  - multitrackTaskId: string (required) — The ID of the multitrack mix task.
  - trackData: array (required) — An array with audio effect settings for each track. Maximum of 32 tracks allowed; each track must be no longer than 8 mins.
  - returnStems: boolean (required) — Whether to return URLs for processed stems.
  - sampleRate: string — Desired sample rate. Use 44100 for 44.1kHz (16-bit) or 48000 for 48kHz (24-bit).
  - webhookURL: string — Optional URL to receive webhook notifications.

POST /masteringpreview
  Creates a mastering task preview.
  - trackData: array (required) — An array containing parameters for the track to be mastered. Only a single item is allowed.

  - musicalStyle: string (required) — The musical style for mastering. Must be one of: ROCK_INDIE, POP, ACOUSTIC, HIPHOP_GRIME, ELECTRONIC, REGGAE_DUB, METAL, OTHER.

  - desiredLoudness: string (required) — Desired loudness preset -- not an exact LUFS guarantee. LOW is quietest/most dynamic (typically around -14 LUFS), MEDIUM is balanced/default (typically around -10 LUFS), and HIGH is loudest/most competitive (typically around -8 LUFS).

  - sampleRate: string — Desired sample rate and bit depth. Options are 44100 (44.1 kHz, 16-bit) or 48000 (48 kHz, 24-bit). Default is 44100.

  - webhookURL: string — Optional URL to receive webhook notifications with status updates for the mastering task.

  - previewStartTime: number — Optional start time in seconds for the 30-second preview segment.
When provided, the preview will be extracted starting at this timestamp
instead of being automatically selected based on highest energy (RMS).
If the specified time would exceed the track duration, it will be
clamped to ensure a valid 30-second segment. If omitted, the default
loudness-based selection is used.


POST /retrievepreviewmaster
  Retrieves the preview mastered track URL.
  - masteringTaskId: string (required) — The mastering task ID provided from the /masteringpreview endpoint.


POST /retrievefinalmaster
  Retrieves the final mastered track URL.
  - masteringTaskId: string (required) — The mastering task ID provided from the /masteringpreview endpoint.


POST /mixanalysis
  Analyses a mixed or mastered track for any problems.
  - audioFileLocation: string (required) — The URL location of the audio file to diagnose.
  - musicalStyle: string (required) — The musical style of the track.
  - isMaster: boolean (required) — Indicates whether the track is a mastered track.

POST /mixenhancepreview
  Generate a preview of an enhanced track with optional stem processing
  - audioFileLocation: string (required) — The URL location of the audio file.
  - musicalStyle: string (required) — The musical style for processing the track.
  - isMaster: boolean — Indicates if the provided audio is already mastered.
  - fixClippingIssues: boolean — Whether to automatically fix clipping issues.
  - fixDRCIssues: boolean — Whether to fix dynamic range compression issues.
  - fixStereoWidthIssues: boolean — Whether to adjust stereo width problems.
  - fixTonalProfileIssues: boolean — Whether to adjust tonal balance issues.
  - fixLoudnessIssues: boolean — Whether to correct loudness discrepancies.
  - applyMastering: boolean — Whether to apply mastering after enhancements.
  - webhookURL: string — Optional URL to receive webhook notifications.
  - loudnessPreference: string — Loudness target for mastering, e.g. CD or streaming.
  - stemProcessing: boolean — Whether to perform stem-based enhancement.
  - previewStartTime: number — Optional start time in seconds for the 30-second preview segment.
When provided, the preview will be extracted starting at this timestamp
instead of being automatically selected based on highest energy (RMS).
If the specified time would exceed the track duration, it will be
clamped to ensure a valid 30-second segment. If omitted, the default
loudness-based selection is used.


POST /mixenhance
  Generate a full length enhanced track with optional stem processing
  - audioFileLocation: string (required) — The URL location of the audio file.
  - musicalStyle: string (required) — The musical style for processing the track.
  - isMaster: boolean — Indicates if the provided audio is already mastered.
  - fixClippingIssues: boolean — Whether to automatically fix clipping issues.
  - fixDRCIssues: boolean — Whether to fix dynamic range compression issues.
  - fixStereoWidthIssues: boolean — Whether to adjust stereo width problems.
  - fixTonalProfileIssues: boolean — Whether to adjust tonal balance issues.
  - fixLoudnessIssues: boolean — Whether to correct loudness discrepancies.
  - applyMastering: boolean — Whether to apply mastering after enhancements.
  - webhookURL: string — Optional URL to receive webhook notifications.
  - loudnessPreference: string — Loudness target for mastering, e.g. CD or streaming.
  - stemProcessing: boolean — Whether to perform stem-based enhancement.
  - previewStartTime: number — Optional start time in seconds for the 30-second preview segment.
When provided, the preview will be extracted starting at this timestamp
instead of being automatically selected based on highest energy (RMS).
If the specified time would exceed the track duration, it will be
clamped to ensure a valid 30-second segment. If omitted, the default
loudness-based selection is used.


POST /retrieveenhancedtrack
  Retrieves the download URL for the final enhanced track.
  - mixReviveTaskId: string (required) — The unique task ID for retrieving the revived track.

POST /audio-cleanup
  Cleans up an audio signal for a specified instrument track.
  - audioFileLocation: string (required) — The URL of the audio file to clean up.
  - soundSource: string (required) — The instrument sound source to clean up.

GET /health
  Health check for the API.

POST /upload
  Get URLs for uploading and accessing an audio file

POST /postprod/dialogue-enhancement/preview
  Create a dialogue enhancement preview task.
  - trackData: array (required) — 
  - sampleRate: integer — Output sample rate in Hz.
  - webhookURL: string — Optional webhook URL for status updates.

POST /postprod/dialogue-enhancement/retrievepreview
  Retrieve dialogue enhancement preview (free).
  - postprodTaskId: string (required) — The task ID from the preview endpoint.

POST /postprod/dialogue-enhancement/retrieve
  Retrieve final dialogue enhancement (charges credits).
  - postprodTaskId: string (required) — 

POST /postprod/delivery-mastering/preview
  Create a delivery format mastering preview task.
  - trackData: array (required) — 
  - deliveryFormat: string (required) — Target delivery format for loudness compliance.
  - sampleRate: integer — 
  - webhookURL: string — 

POST /postprod/delivery-mastering/retrievepreview
  Retrieve delivery mastering preview (free).
  - postprodTaskId: string (required) — 

POST /postprod/delivery-mastering/retrieve
  Retrieve final delivery mastering (charges credits).
  - postprodTaskId: string (required) — 

POST /postprod/loudness-check
  Submit a loudness/LRA compliance check (analysis only, no processing).
  - trackData: array (required) — 
  - deliveryFormat: string (required) — 
  - webhookURL: string — 

POST /postprod/loudness-check/retrieve
  Retrieve loudness check results (charges credits).
  - postprodTaskId: string (required) — 

POST /postprod/ducking/preview
  Create a sidechain ducking preview task (multi-track).
  - trackData: array (required) — 
  - generateStems: boolean — If true, return individually processed stems (+50 credits).
  - sampleRate: integer — 
  - webhookURL: string — 

POST /postprod/ducking/retrievepreview
  Retrieve ducking preview (free).
  - postprodTaskId: string (required) — 

POST /postprod/ducking/retrieve
  Retrieve final ducking result (charges credits).
  - postprodTaskId: string (required) — 

POST /postprod/full-mix/preview
  Create a full post-production mix preview task (multi-track).
  - trackData: array (required) — 
  - deliveryFormat: string (required) — 
  - generateStems: boolean — If true, return individually processed stems (+50 credits).
  - sampleRate: integer — 
  - webhookURL: string — 

POST /postprod/full-mix/retrievepreview
  Retrieve full mix preview (free).
  - postprodTaskId: string (required) — 

POST /postprod/full-mix/retrieve
  Retrieve final full mix result (charges credits).
  - postprodTaskId: string (required) — 

POST /postprod/adr-matching/preview
  Create an ADR-to-location matching preview task.
  - trackData: array (required) — Exactly 2 tracks — one with role REFERENCE, one with role ADR.
  - sampleRate: integer — 
  - webhookURL: string — 

POST /postprod/adr-matching/retrievepreview
  Retrieve ADR matching preview (free).
  - postprodTaskId: string (required) — 

POST /postprod/adr-matching/retrieve
  Retrieve final ADR matching result (charges credits).
  - postprodTaskId: string (required) — 

POST /separate
  Split a stereo track into stems (vocals, drums, bass, other) or vocals + instrumental.
  - audioFileLocation: string (required) — URL of the stereo audio file to separate (WAV, FLAC, or MP3).
  - separationMode: string — all_stems (default) returns vocals, drums, bass, other. vocals_instrumental returns vocals + instrumental.
  - webhookURL: string — Optional URL to receive async status notifications for this separation job.

GET /separatestatus/{stemflow_task_id}
  Poll stem separation task status.

POST /retrievestems
  Retrieve the 4 separated stem URLs (free).
  - stemflowTaskId: string (required) — 

POST /recombine
  Mix a vocal against a backing track/beat and master the result (free to submit).
  - stemJobId: string — A completed stemflowTaskId from a prior /separate call.
  - vocalStemURL: string — URL of a vocal-only recording. Must be owned or licensed by the caller.
  - backingStemURL: string — URL of the backing track/instrumental/beat to mix the vocal against. Must be owned or licensed by the caller.
  - musicalStyle: string (required) — Required. Same enum as /masteringpreview's musicalStyle; materially affects the mix and master.
  - desiredLoudness: string — Mastering loudness preset, same as /masteringpreview: LOW is quietest/most dynamic, MEDIUM is the balanced default, HIGH is loudest/most competitive. Selects a preset, not an exact LUFS value. Defaults to MEDIUM if omitted.

  - vocalGainDb: number — Optional adjustment to the vocal level, in dB, relative to Tonn's automatically-mixed balance (not an absolute fader position). Positive values bring the vocal forward; negative values tuck it into the backing. 0.0 (default) keeps the automatic balance unchanged. Range -6.0 to 6.0; try small +/-1-3 dB moves before the extremes. Does not control pan, reverb, EQ, compression, or backing level.

  - webhookURL: string — Optional URL to receive async status notifications for this recombine job.

GET /recombinestatus/{recombine_task_id}
  Poll recombine task status.

POST /retrieverecombinepreview
  Retrieve a free 30-second MP3 preview of the recombined master.
  - recombineTaskId: string (required) — 

POST /retrieverecombine
  Retrieve the final mastered WAV (charges 250 credits, once).
  - recombineTaskId: string (required) — 

## Full OpenAPI Specification
https://tonn-portal.roexaudio.com/openapi.json

## Documentation
https://tonn-portal.roexaudio.com/docs/

## Python Client
pip install roex-python
https://pypi.org/project/roex-python/