# Advanced soundtracking

## Getting the mp3 file using `soundtrack` endpoint

For more complex requests and full control of your soundtrack please use `/soundtrack` endpoint. It accepts two parameters which is the list (array) of [regions](/muzaic-api-docs/reference/api-reference/soundtrack.md#region-object-definition) and a normalization directive.

## Generates and bounces a soundtrack

<mark style="color:green;">`POST`</mark> `/soundtrack`

#### Request Body

| Name                                      | Type   | Description                                                                                                     |
| ----------------------------------------- | ------ | --------------------------------------------------------------------------------------------------------------- |
| regions<mark style="color:red;">\*</mark> | JSON   | An Array of [regions](/muzaic-api-docs/reference/api-reference/soundtrack.md#region-object-definition).         |
| normalize                                 | String | Enables soundtrack [loudness normalization](#normalizing-soundtrack). Accept values: `none`, `auto` and `high`. |

{% tabs %}
{% tab title="200: OK File successfully generated" %}

```json
// Sample response

{
    "apiVersion":"1.2.0",
    "mp3": "https://m10.muzaic.ai/result/2024-01-31/st_3b12463ea3ecc474e22ebc302e70a0b3.mp3",
    "regions":[{"number":0,"hash":"6cc0b6861d5d369ec475d7236e9bfb63"},{"number":1,"hash":"9191593eb3992ba7c4307455c0e1b5ca"}],
    "status": "region 0 normalize: none | region 1 no params object | soundtrack normalized: auto",
    "tokensUsed": 65,
    "executionTime": 5.111389875412
}
```

{% endtab %}

{% tab title="400: Bad Request Bad request" %}

```json
//example response

{
    "Error": "No regions list"
}
```

{% endtab %}
{% endtabs %}

## Example requests&#x20;

{% hint style="info" %}
**Good to know:** For fields `tags` and `params` similar rules and limitations apply for regions as for a [single file](/muzaic-api-docs/reference/getting-the-music/quickly-getting-an-audio-file.md) generation.&#x20;
{% endhint %}

#### Request with two regions

Here's a typical request for a 48-second soundtrack, starting with a generated region using the [keyframes](#understanding-keyframes-arrays) feature, followed by fixed jingle at the 20.2-second time mark.

```json
{
    "regions": [
        {
            "time":0,
            "duration":20.2,
            "tags":[17],
            "params": {
                "intensity":[[0,1],[100,9]],
                "tempo":5,
                "rhythm":[[0,9],[100,1]],
                "tone":[[0,9],[100,1]],
                "variance":[[0,5],[100,5]]
            },
            "method":"adjust_end"
        },
        {
            "time":20.2,
            "duration":27.8,
            "sourceHash":"9191593eb3992ba7c4307455c0e1b5ca",
            "action":"copy",
            "method":"adjust_start"
        }    
    ]
}
```

## Understanding regions

Regions are distinct segments of a soundtrack, each with its own defined start time and duration. The structure and logic of these regions are crucial for shaping the overall music effect. Muzaic API relies on the provided request data to perform the generation process and won't be making any changes to logical structure of the music piece (except some overall time adjustments, when certain `method` values are set).&#x20;

{% hint style="info" %}
**Good to know:** Regions offer a wide range of possibilities. Need to make room for a speaking person? Define a low-intensity region. Want to introduce silence? Adjust the time field accordingly and push forward the next region in time.
{% endhint %}

## Understanding keyframes arrays

Muzaic API allows you to shape the music the way you desire. If you wish for the music to have variations between the beginning and end of a piece, you should utilize the keyframes array. This array is specially designed to describe the changes in specific values over time.

{% hint style="warning" %}
**Good to know:** In the current Muzaic API version, providing keyframes array for `tempo` parameter is not supported.
{% endhint %}

#### Example keyframe array

```json
"intensity":[[0,5],[100,9]]
```

Keyframe arrays consist of pairs, where the first number represents a relative percentage of the total duration of a music region or file, and the second number represents a parameter value. While you can include an unlimited number of keyframes, it is mandatory to have a starting keyframe with a first number of 0 and an ending keyframe with a first number of 100. The percentage can be an `integer` or a `float`, while the parameter value must be an `integer` between 1 and 9. In the example mentioned above, the `intensity` parameter will increase from 5 to 9 during the duration of a music fragment.

{% hint style="info" %}
**Good to know:** In the current version of the Muzaic API, keyframe arrays yield the best results for music files or regions longer than 60 seconds.
{% endhint %}

## Hashes

Each Muzaic generation receives a unique hash which represents it in the system. Use these hashes to link your calls to previously generated audios. Hashes are needed when you want to insert a part of music into your soundtrack, regenerate some regions, or extend composition that you've liked.

#### Example of hash usage for extending a region

```json
{
    "regions": [
        {
            "time":0,
            "duration":50,
            "sourceHash":"9191593eb3992ba7c4307455c0e1b5ca",
            "action":"extend"
        }    
    ]
}
```

{% hint style="info" %}
**Good to know:** Obtain hashes with every response.
{% endhint %}

## Using the `action` field

The `action` field controls the generation process, enabling you to maximize the use of previously generated music. Want to copy an entire passage? Create more music based on this fragment? Or maybe just regenerate with the same settings?

{% hint style="info" %}
**Good to know:** For all actions except "generate", you need to pass a [hash](#hashes) value in your request with `sourceHash` parameter.
{% endhint %}

#### Action field values

<table><thead><tr><th width="171.35546875">Value</th><th>Behaviour</th></tr></thead><tbody><tr><td>"generate"</td><td>Generates a region with provided settings. A default value. </td></tr><tr><td>"copy"</td><td>Makes a direct copy of the region provided by the <code>sourceHash</code> parameter.</td></tr><tr><td>"regenerate"</td><td>Makes a new version of the region provided by the <code>sourceHash</code> parameter. </td></tr><tr><td>"change_duration"</td><td>Copies the region provided by the <code>sourceHash</code> parameter and changes  <code>duration</code> .</td></tr></tbody></table>

{% hint style="info" %}
**Good to know:** Remember to include the `duration` parameter in your request, even when using the "copy" or "regenerate" action. You can freely change the `duration`, even with these specific actions, to create a slightly longer or shorter file.
{% endhint %}

## Using the `method` field

The `method` field is responsible for interpreting the structure of the soundtrack. Sometimes, there's a need for exactly 20 seconds of an audio file, and sometimes for 20 seconds of music. Where's the difference? Consider having a video that lasts for 60 seconds, but that doesn't mean the accompanying audio is also 60 seconds long. Often, there's a 'tail' that includes and conveys other messages. You may want the music to end at 60 seconds, but not abruptly. Naturally, you would say, 'with decay.' Muzaic understands this if you specify it.

This is also crucial when merging different regions – you can use the `method` values to achieve the desired effect.

{% hint style="success" %}
**Good to know:** Method field is not required.
{% endhint %}

#### Method field values

<table><thead><tr><th width="159">Value</th><th>Behaviour</th></tr></thead><tbody><tr><td>"strict"</td><td>The <code>time</code> and <code>duration</code> are interpreted as they are. The buildup starts at <code>time</code> value and decay is finished exactly at the <code>duration</code> point.</td></tr><tr><td>"auto_adjust"</td><td>The buildup begins earlier, with the first beat of the music occurring at the specified <code>time</code> value, while the decay commences at the <code>duration</code> point and naturally extends beyond it.</td></tr><tr><td>"adjust_start"</td><td>The buildup starts before the <code>time</code> value but the decay ends within the <code>duration</code> limit.</td></tr><tr><td>"adjust_end"</td><td>The buildup starts precisely at the specified <code>time</code> value, while the decay commences after the <code>duration</code> point.</td></tr></tbody></table>

{% hint style="warning" %}
**Good to know:** You can only use "adjust\_end" or "strict" method values when region `time` value is set really low. The forced change of method may occur for a `time` value up to 4 seconds.
{% endhint %}

## Normalizing your soundtrack

With the Muzaic API, you can normalize your generated soundtrack using `normalize` field. Use one of three values:

* `none` – This mode leaves the soundtrack as it was generated. This is the best option when there's an additional layer of audio, such as someone talking, original sound effects, or other background sounds.
* `auto` – This mode will normalize the soundtrack according to the EBU R128 standard. It's best for videos or parts of videos where the music should be in the foreground.
* `high` – This mode will normalize the soundtrack to a higher level of loudness.

#### Example request with normalization feature

```json
{
    "normalize": "auto",
    "regions": [
        {
            "time":0,
            "duration":16,
            "tags":[17]
        },
        {
            "time":16,
            "duration":17.4,
            "tags":[2,11]
        }    
    ]
}
```

## Response handling

If your request is valid, the response from the `/soundtrack` endpoint resembles that of a [singleFile](/muzaic-api-docs/reference/getting-the-music/quickly-getting-an-audio-file.md) . It includes a URL to the created MP3 file (`mp3`), as well as `status`, `tokensUsed,` `executionTime` fields (in seconds) and `apiVersion`. Additionally, it contains a `regions` array for obtaining [hashes](#hashes) of the created music pieces

#### Example response

```json
{
  "apiVersion": "2.0.0",
  "status": [
    "soundtrack wrong normalize value – default used"
  ],
  "regions": 1,
  "regionDetails": [
    {
      "hash": "d09dfaba17483c82141968fbd576804eda6ca7728d2806db241718749181c242",
      "name": "Heavy Rock Rebellion",
      "iconUrl": "https://musicpool.muzaic.ai/generated_icons/d09dfaba17483c82141968fbd576804eda6ca7728d2806db241718749181c242.png"
    }
  ],
  "audioDuration": 4.9202276166055805,
  "soundtrackHash": "645a22dae0ccbdf9010eeee4715a2da0",
  "tokensUsed": 5,
  "soundtrackIcon": "https://musicpool.muzaic.ai/generated_icons/236e24473eb83a73ad97242ed6d1d453.png",
  "mp3": "https://m10.muzaic.ai/result/2024-01-31/st_3b12463ea3ecc474e22ebc302e70a0b3.mp3",
  "executionTime": 1.276
}
```

## List of statuses

With a Muzaic API call, you will always be provided with a music response. However, depending on your request, you may receive different statuses, and these statuses can stack.

<table><thead><tr><th width="220">Status</th><th>Meaning</th></tr></thead><tbody><tr><td>no tags</td><td>No <code>tags</code> parameter provided in a request</td></tr><tr><td>wrong tags format</td><td>Provided <code>tags</code> parameter is not an Array of integers</td></tr><tr><td>no duration</td><td>No <code>duration</code> parameter provided in a request</td></tr><tr><td>wrong duration format</td><td>Provided <code>duration</code> parameter is not a float</td></tr><tr><td>wrong source hash</td><td>Provided <code>sourceHash</code> parameter is wrong</td></tr><tr><td>no action</td><td>No <code>action</code> parameter provided, default used</td></tr><tr><td>wrong action</td><td>Wrong <code>action</code> parameter provided, default used</td></tr><tr><td>no params object</td><td>No <code>params</code> JSON object provided in a request</td></tr><tr><td>wrong param: [param name]</td><td>The parameter [param name] in <code>params</code> JSON object is not set properly or is not an integer</td></tr><tr><td>wrong param key frames: [param name]</td><td>Wrong <a href="#understanding-keyframes-arrays">keyframe array</a> in the parameter [param name] in <code>params</code> JSON object.</td></tr><tr><td>region [number] action: [type]</td><td>Performed certain action on a given region</td></tr><tr><td>soundtrack normalized: [type]</td><td>Performed soundtrack loudness normalization</td></tr></tbody></table>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.muzaic.ai/muzaic-api-docs/reference/getting-the-music/advanced-soundtracking.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.