### Install apiaudio from Source

Source: https://github.com/aflr-archive/apiaudio-python/blob/main/README.md

Install the apiaudio package directly from its source code using setup.py. This is useful if you need to modify the library's code.

```sh
python setup.py install
#or
python3 setup.py install
```

--------------------------------

### Preview Script with Pronunciation Dictionary

Source: https://github.com/aflr-archive/apiaudio-python/blob/main/README.md

Previews a script to demonstrate the effect of the Pronunciation Dictionary. This example shows how custom pronunciations for 'Bude' and 'Bristol' would be handled.

```python
text = """
      The author of this repo has lived in two places in the
      UK, <!Bude> and <!Bristol>
    """

r = apiaudio.Script.create(scriptText=text)
scriptId = r["scriptId"]

# preview the script in en-gb
preview = apiaudio.Script.preview(scriptId=scriptId, voice="Joanna")
print(preview)

```

```python
{"preview" : "The author of this repo has lived in two places in the UK, bude and <phoneme alphabet=\"ipa\" ph=\"###\"> bristol </phoneme>"}

```

--------------------------------

### List Modules by Project Prefix

Source: https://github.com/aflr-archive/apiaudio-python/blob/main/README.md

Lists all module names that start with a given project prefix. Helps in navigating script organization.

```python
#Lists all module names
modules = apiaudio.Script.Directory.list_modules(projectPrefix="workout")

print(modules)
# example output: ["workout_1/over60s", "workout_2/morning_routine"]
```

--------------------------------

### Create and Process Audio with Cereproc Voice

Source: https://github.com/aflr-archive/apiaudio-python/blob/main/CHANGELOG.md

Example demonstrating how to create a script, generate speech using a Cereproc voice, apply mastering, and download the audio file.

```python
import apiaudio
apiaudio.api_key="API-KEY"
script = apiaudio.Script.create(scriptText="<<soundSegment::intro>><<sectionName::intro>>Hello world. Welcome to API dot audio.<<soundSegment::main>><<sectionName::main>> Create audio in a few easy steps.")
response = apiaudio.Speech.create(scriptId=script.get("scriptId"), voice="dakota")
response = apiaudio.Mastering.create(scriptId=script.get("scriptId"), soundTemplate = "parisianmorning" )
file = apiaudio.Mastering.download(scriptId=script.get("scriptId"))
```

--------------------------------

### Create Speech - Complete Example

Source: https://github.com/aflr-archive/apiaudio-python/blob/main/README.md

Use this snippet for a comprehensive speech creation request, including all available parameters for advanced customization.

```python
response = apiaudio.Speech.create(
    scriptId="id-1234",
    version="abc",
    voice="Matthew",
    speed=100,
    effect="dark_father",
    silencePadding= 1000,
    sync=True,
    audience={"username": "Elon", "lastname": "Musk"},
    sections={
        "firstsection": {
            "voice": "Matthew",
            "speed": 110,
            "silence_padding": 100,
        },
        "anothersection": {
            "voice": "Liam",
        }
    }
    )
```

--------------------------------

### Install apiaudio Python Package

Source: https://github.com/aflr-archive/apiaudio-python/blob/main/README.md

Install the apiaudio Python package using pip. Use the -U flag to ensure you get the latest version.

```sh
pip install apiaudio -U
#or
pip3 install apiaudio -U
```

--------------------------------

### Create Speech - Simple Example

Source: https://github.com/aflr-archive/apiaudio-python/blob/main/README.md

Use this snippet for a basic speech creation request, specifying only the script ID and voice.

```python
response = apiaudio.Speech.create(
    scriptId="id-1234",
    voice="Joanna"
    )
```

--------------------------------

### List Projects

Source: https://github.com/aflr-archive/apiaudio-python/blob/main/CHANGELOG.md

Lists all projects within your organization. Use the GET /script/list_projects endpoint.

```python
apiaudio.script.list_projects() OR (GET) /script/list_projects
```

--------------------------------

### Create Media Timeline for Mastering

Source: https://github.com/aflr-archive/apiaudio-python/blob/main/README.md

Use this to define a timeline with speech and background sound files for mastering. Specify media IDs, start and end times, and the mastering preset.

```python
timeline = [
  {
      "files" : [
          {
              "mediaId" : speechId,
              "startAt" : 2,
              "endAt" : 14,
          }
      ],
      "contentType" : "speech"
  },
  {

      "files" : [
          {
              "mediaId" : backgroundId,
              "startAt" : 0,
              "endAt" : 45,
          }
      ],
      "contentType" : "sound"
  }
]
response = apiaudio.Mastering.create_media_timeline(timeline=timeline, masteringPreset="lightducking")
```

--------------------------------

### List Modules

Source: https://github.com/aflr-archive/apiaudio-python/blob/main/CHANGELOG.md

Lists all modules within your organization. The values returned will be in the format <project_name>/<module_name>. Use the GET /script/list_modules endpoint.

```python
apiaudio.script.list_modules() OR (GET) /script/list_modules
```

--------------------------------

### Sound Resource - List Sound Templates

Source: https://github.com/aflr-archive/apiaudio-python/blob/main/README.md

Lists all available sound templates in the API. Supports filtering by industry examples, contents, genre, tempo, and tags.

```APIDOC
## Sound Resource - List Sound Templates

### Description
Lists all available sound templates in the API. Supports filtering by industry examples, contents, genre, tempo, and tags.

### Method
GET (assumed, based on SDK method)

### Endpoint
/sounds (assumed, based on SDK method)

### Parameters
#### Query Parameters
- **industryExamples** (string) - Optional - Try with one or more (separated by commas) of: news, travel, business, relaxation, fitness, relax, children stories
- **contents** (string) - Optional - Try with one or more (separated by commas) of: intro, main, outro, effect1, effect2, main outro, droid_main, chewie_main, effect3, ambience, only effects
- **genre** (string) - Optional - Try with one of: electronic, acoustic, atmospheric, abstract, rock
- **tempo** (string) - Optional - Try with one of: mid, up, down, uptempo
- **tags** (string) - Optional - Try with one or more (separated by commas) of: intense, minimal, reflective, melodic, happy, nostalgic, focus, energetic, uplifting, active, relaxed, ambience, mysterious, positive, informative, workout, work, meditation, travel, full silence

### Request Example
```python
sound_templates = apiaudio.Sound.list()
```
```

--------------------------------

### Master Audio with Sound Template

Source: https://github.com/aflr-archive/apiaudio-python/blob/main/README.md

Combine the synthesized speech with a sound template to create a mastered audio asset. The 'jakarta' template is used in this example.

```python
response = apiaudio.Mastering.create(
	scriptId=script.get("scriptId"),
	soundTemplate="jakarta"
	)
print(response)
```

--------------------------------

### Retrieve a script by ID and version

Source: https://github.com/aflr-archive/apiaudio-python/blob/main/README.md

Retrieve a specific script using its ID. Optionally, specify a version to get a particular version of the script; otherwise, it defaults to the main version (v0).

```python
script = apiaudio.Script.retrieve(scriptId="id-1234", version="abc")
```

--------------------------------

### Get Media File Download URL

Source: https://github.com/aflr-archive/apiaudio-python/blob/main/README.md

Generates a presigned URL for downloading a specific audio file using its media ID. This URL is temporary and allows direct download access.

```python
url = apiaudio.Media.get_download_url(mediaId="some-mediaId")
print(url)
```

--------------------------------

### Complete Hello World Script

Source: https://github.com/aflr-archive/apiaudio-python/blob/main/README.md

This is the complete 'hello.py' file, integrating all steps from authentication to downloading the audio asset.

```python
import apiaudio
apiaudio.api_key = "your-key"

# script creation
script = apiaudio.Script.create(scriptText="Hello world")

# speech creation
response = apiaudio.Speech.create(scriptId=script["scriptId"], voice="Aria")

print(response)

# mastering process
response = apiaudio.Mastering.create(
	scriptId=script.get("scriptId"),
	soundTemplate="jakarta"
	)
print(response)

# download
filepath = apiaudio.Mastering.download(scriptId=script["scriptId"], destination=".")
print(filepath)
```

--------------------------------

### Run the Python Script

Source: https://github.com/aflr-archive/apiaudio-python/blob/main/README.md

Execute the 'hello.py' script using either python or python3 to generate and download the audio asset.

```sh
python hello.py
#or
python3 hello.py
```

--------------------------------

### Create a Python File

Source: https://github.com/aflr-archive/apiaudio-python/blob/main/README.md

Create a new Python file named 'hello.py' to write your audio generation script.

```sh
touch hello.py
```

--------------------------------

### Get Organization Data

Source: https://github.com/aflr-archive/apiaudio-python/blob/main/CHANGELOG.md

Retrieves organization data including ID and name. No parameters are required.

```python
org_data = apiaudio.Organization.get_org_data()
```

--------------------------------

### Get API Secrets

Source: https://github.com/aflr-archive/apiaudio-python/blob/main/CHANGELOG.md

Retrieves API key, webhook URL, and webhook secret. No parameters are required.

```python
secrets = apiaudio.Organization.get_secrets()
```

--------------------------------

### Specific Resource Import and Usage

Source: https://github.com/aflr-archive/apiaudio-python/blob/main/README.md

Alternatively, import specific resource classes like 'Script' first, and then use their methods. This approach is useful when you only need a few resources.

```python
from apiaudio import Script
Script.create()
```

--------------------------------

### Organization Resource Methods

Source: https://github.com/aflr-archive/apiaudio-python/blob/main/README.md

Methods for retrieving organization data, listing child organizations, and getting API secrets.

```APIDOC
## Organization Resource

### Description
The Organization resource/class allows you to perform data retrieval about your organization and your child organizations.

### Methods

#### `get_org_data()`

- **Description**: Get organizations data, including orgId, orgName etc.
- **Parameters**: None.
- **Example**:
  ```python
  org_data = apiaudio.Organization.get_org_data()
  ```

#### `list_child_orgs()`

- **Description**: List your child organizations.
- **Parameters**: None.
- **Example**:
  ```python
  child_orgs = apiaudio.Organization.list_child_orgs()
  ```

#### `get_secrets()`

- **Description**: Get your api key, webhook url and webhook secret.
- **Parameters**: None.
- **Example**:
  ```python
  secrets = apiaudio.Organization.get_secrets()
  ```
```

--------------------------------

### Get Random Text from Category

Source: https://github.com/aflr-archive/apiaudio-python/blob/main/README.md

Retrieves a random text snippet from a specified category. Defaults to 'FunFact' if no category is provided.

```python
text = apiaudio.Script.get_random_text(category="BibleVerse")
```

--------------------------------

### Authenticate with API Key

Source: https://github.com/aflr-archive/apiaudio-python/blob/main/README.md

Import the apiaudio library and set your account's API key. Obtain your API key from the api.audio Console.

```python
import apiaudio
apiaudio.api_key = "your-key"
```

--------------------------------

### Mastering with Share Functionality

Source: https://github.com/aflr-archive/apiaudio-python/blob/main/CHANGELOG.md

Create a mastering job with the option to share the audio. The response includes a share URL for easy distribution.

```python
mastering = apiaudio.Mastering.create(
scriptId="concert-ad",
soundTemplate="house",
share=True
)
# Check the response
print('Response from mastering', mastering)

# Listen and share your audio file 
print('Listen to your audio here', mastering['shareUrl'])
```

```shell
Response from mastering {'shareUrl': 'https://console.api.audio/share?id=e3b91a92', 'message': 'Mastering completed successfully', 'url': 'https://v1.api.audio/url/aaecb3/concert-ad__band~nickelback__city~berlin.mp3', 'warnings': ''}
Listen to your audio here https://console.api.audio/share?id=e3b91a92
```

--------------------------------

### Create and Download Mastered Audio with Script

Source: https://github.com/aflr-archive/apiaudio-python/blob/main/CHANGELOG.md

Create a script, then generate and download mastered audio using a specific voice, sound template, and mastering preset. This demonstrates leveraging digital signal processing and machine learning for audio enhancement.

```python
import apiaudio

apiaudio.api_base = "https://v1.api.audio"
apiaudio.api_key = ""

template = "3am"   

preset = "excitermaster" 
name = "gabriel"            
text = f"""Hi I am {name} using the preset {preset} and the {template} sound template, presenting our new exciter plug-in, to enhance the clarity of our mixes"""

response = apiaudio.Script.create(scriptText=text, scriptName=f"demo-{name}-{preset}", projectName = "demo")
script_id = response["scriptId"]
response = apiaudio.Speech.create(scriptId=script_id, voice=name)

r = apiaudio.Mastering.create(scriptId=script_id, soundTemplate=template, masteringPreset = preset) 
print(r)

r = apiaudio.Mastering.download(scriptId=script_id)
```

--------------------------------

### List All Projects

Source: https://github.com/aflr-archive/apiaudio-python/blob/main/README.md

Lists all available project names in the directory. Useful for understanding the project structure.

```python
#Lists all project names
projects = apiaudio.Script.Directory.list_projects()
print(projects)
# example output: ["projectX", "projectY"]
```

--------------------------------

### Create and Use German Voice Script

Source: https://github.com/aflr-archive/apiaudio-python/blob/main/CHANGELOG.md

Demonstrates creating a script with German text, generating speech using the 'margareta-v1' voice, and applying a sound template for mastering. Includes downloading the mastered audio file.

```python
# script text
text = text = """
Hallo Peadar. Ich wurde am 20.06.2022 in der Softwareschmiede von Aflorithmic in Produktion eingesetzt.
"""
# script creation
script = apiaudio.Script.create(scriptText=text, scriptName="breaking_news")

r = apiaudio.Speech().create(
    scriptId=script.get("scriptId"),
    voice="margareta-v1",
    speed=110,
)

template = "breakingnews"
response = apiaudio.Mastering().create(
    scriptId=script.get("scriptId"),
    soundTemplate=template
)

print(response)

file = apiaudio.Mastering().download(
    scriptId=script.get("scriptId"), destination=".")
print(file)
```

--------------------------------

### Import the apiaudio library

Source: https://github.com/aflr-archive/apiaudio-python/blob/main/README.md

Import the main apiaudio library to begin using its functionalities.

```python
import apiaudio
```

--------------------------------

### Create a new script with versions

Source: https://github.com/aflr-archive/apiaudio-python/blob/main/README.md

This method allows creating a script with a default text and multiple language versions defined in a dictionary. The key is the version name (e.g., 'es', 'en') and the value is the script text for that version.

```python
script = apiaudio.Script.create(
        scriptText="Default text",
        versions={"es" : "Hola", "en" : "hello"}
        )
```

--------------------------------

### Orchestrator.media_with_sound()

Source: https://github.com/aflr-archive/apiaudio-python/blob/main/README.md

Combines a pre-existing media file with a sound template.

```APIDOC
## Orchestrator.media_with_sound()

### Description
Combines a pre-existing media file (i.e. pre-recorded voice) with a sound template.

### Method
media_with_sound()

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **mediaId** (str) - Required - MediaId of the media file to use as input.
- **soundTemplate** (str) - Required - Sound template to use.

### Request Example
```python
apiaudio.Orchestrator.media_with_sound(
  mediaId="a1b2c3d4-e5f6-7890-1234-567890abcdef",
  soundTemplate="default"
)
```

### Response
#### Success Response (200)
- **audio_id** (string) - The ID of the created audio.
- **status** (string) - The status of the audio creation process.

#### Response Example
```json
{
  "audio_id": "c3d4e5f6-a7b8-9012-3456-7890abcdef12",
  "status": "processing"
}
```
```

--------------------------------

### Voice Resource - List Voices

Source: https://github.com/aflr-archive/apiaudio-python/blob/main/README.md

Lists all available voices from the API. Supports filtering by provider, language, accent, gender, age bracket, tags, industry examples, time performance, and section character limit.

```APIDOC
## Voice Resource - List Voices

### Description
Lists all available voices from the API. Supports filtering by provider, language, accent, gender, age bracket, tags, industry examples, time performance, and section character limit.

### Method
GET (assumed, based on SDK method)

### Endpoint
/voices (assumed, based on SDK method)

### Parameters
#### Query Parameters
- **provider** (string) - Optional - Try one of: google, polly, azure, msnr (aflorithmic), ibm, yandex, retro (aflorithmic), vocalid, resemble
- **language** (string) - Optional - e.g. english, spanish, french, german, etc.
- **accent** (string) - Optional - e.g. american, british, neutral, portuguese/brazilian, american soft, mexican, australian
- **gender** (string) - Optional - Try with one of: male, female
- **ageBracket** (string) - Optional - Try with one of: adult, child, senior
- **tags** (string) - Optional - Try with one or more (separated by commas) of: steady, confident, balanced, informative, serious, instructional, slow, storytelling, calm, clear, deep, formal, sad, thin, fast, upbeat, fun, energetic, tense, very fast, flat, low pitched, high pitched, low-pitched, sing-y, cooperative, kind, stable, monotonous, neutral, responsible, business man, straight to the point, knowledgeable, focused, newscastery, newsreader, interviewer, reliable, friendly, welcoming, good for handing out information, slightly friendly
- **industryExamples** (string) - Optional - Try with one or more (separated by commas) of: fitness, business, commercial, fashion, travel, audiobook, real estate, faith, health industry, comercial, realestate, kids entertainment, games, customer service, education, storytelling, entertainment, kids, education audiobook
- **timePerformance** (string) - Optional - The time performance of the voice. There are three categories: slow, medium, fast.
- **sectionCharacterLimit** (string) - Optional - The maximum amount of characters that the voice can process per Script section. All of the supported providers with the exception of VocalId have the limit of 4000.

### Request Example
```python
all_voices = apiaudio.Voice.list()
```

### Request Example 2
```python
french_voices = apiaudio.Voice.list(language="french",tags="steady, fun")
```
```

--------------------------------

### Create a new script with text and metadata

Source: https://github.com/aflr-archive/apiaudio-python/blob/main/README.md

Use this method to create a new script with specified text, project, module, script names, and metadata. The script text can include sections and SSML tags.

```python
text = "<<sectionName::hello>> Hello {{username|buddy}} 
      <<sectionName::bye>> Good bye from {{location|barcelona}}"
    
    script = apiaudio.Script.create(
        scriptText=text,
        projectName="myProject",
        moduleName="myModule",
        scriptName="myScript",
        scriptId="id-1234",
        metadata={"author" : "sam", "tags" : ["demo", "intro"]}
        )
```

--------------------------------

### Direct Resource Import and Usage

Source: https://github.com/aflr-archive/apiaudio-python/blob/main/README.md

Import all resources directly from the apiaudio library and call their methods. This is the recommended approach for using SDK resources.

```python
import apiaudio
apiaudio.Script.create()
```

--------------------------------

### Mastering.list_presets

Source: https://github.com/aflr-archive/apiaudio-python/blob/main/README.md

Lists all available mastering presets.

```APIDOC
## Mastering.list_presets

### Description
Lists the available mastering presets that can be used when creating mastered media timelines.

### Method
GET (inferred from SDK usage)

### Endpoint
/v1/mastering/presets (inferred from SDK usage)

### Parameters
No parameters required.

### Request Example
```python
presets = apiaudio.Mastering.list_presets()
print(presets)
```
```

--------------------------------

### Script.create()

Source: https://github.com/aflr-archive/apiaudio-python/blob/main/README.md

Creates a new script with specified text, project, module, name, ID, versions, and metadata. It allows for detailed configuration of script content and organization.

```APIDOC
## Script.create()

### Description
Creates a new script with specified text, project, module, name, ID, versions, and metadata. It allows for detailed configuration of script content and organization.

### Method
```python
apiaudio.Script.create(
    scriptText: str,
    projectName: str = "default",
    moduleName: str = "default",
    scriptName: str = "default",
    scriptId: str = None,
    versions: dict = {},
    metadata: dict = {}
)
```

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **scriptText** (string) - Required - Text for your script. A script can contain multiple sections and SSML tags.
- **projectName** (string) - Optional - The name of your project. Default value is "default" (max 60 characters).
- **moduleName** (string) - Optional - The name of your module. Default value is "default" (max 60 characters).
- **scriptName** (string) - Optional - The name of your script. Default value is "default" (max 60 characters).
- **scriptId** (string) - Optional - Custom identifier for your script. If scriptId parameter is provided, then projectName, moduleName and scriptName are set to the same value as scriptId.
- **versions** (dictionary) - Optional - A dictionary containing different versions of your script text, whereby the key is the version name, and its value is the associated `scriptText`. Version name `v0` is reserved as the default `scriptText`. Default value is "{}".
- **metadata** (dictionary) - Optional - Metadata for your script. This is limited to 2kb in size.

### Request Example
```python
text = """
  <<sectionName::hello>> Hello {{username|buddy}} 
  <<sectionName::bye>> Good bye from {{location|barcelona}}
"""

script = apiaudio.Script.create(
    scriptText=text,
    projectName="myProject",
    moduleName="myModule",
    scriptName="myScript",
    scriptId="id-1234",
    metadata={"author" : "sam", "tags" : ["demo", "intro"]}
    )
# example 2 with versions
script = apiaudio.Script.create(
    scriptText="Default text",
    versions={"es" : "Hola", "en" : "hello"}
    )
```

### Response
#### Success Response (200)
Details of the created script.

#### Response Example
```json
{
  "scriptId": "id-1234",
  "scriptName": "myScript",
  "projectName": "myProject",
  "moduleName": "myModule",
  "versions": {
    "v0": "Default text",
    "es": "Hola",
    "en": "hello"
  },
  "metadata": {
    "author": "sam",
    "tags": ["demo", "intro"]
  }
}
```
```

--------------------------------

### Script.preview()

Source: https://github.com/aflr-archive/apiaudio-python/blob/main/README.md

Returns a script with dictionary highlighting applied, useful for previewing script content with specific formatting or tags.

```APIDOC
## Script.preview()

### Description
Returns a script with dictionary highlighting applied, useful for previewing script content with specific formatting or tags.

### Method
```python
apiaudio.Script.preview(
    scriptId: str,
    voice: str,
    language: str = None
)
```

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **scriptId** (string) - Required - The script ID you want to use.
- **voice** (string) - Required - The voice that will be used to render speech. This is required as the output can be dependent on voice, language code, or provider.
- **language** (string) - Optional - The language code for the voice. 

### Request Example
```python
text = """
  The author of this repo has lived in two places in the
  UK, <!location>Bude<!> and <!location>Bristol<!>.
"

r = apiaudio.Script.create(scriptText=text)
scriptId = r["scriptId"]

preview = apiaudio.Script.preview(scriptId=scriptId, language="en-gb")
```

### Response
#### Success Response (200)
Preview of the script with highlighting applied.

#### Response Example
```json
{
  "previewText": "The author of this repo has lived in two places in the UK, Bude and Bristol.",
  "audioUrl": "https://example.com/audio.mp3"
}
```
```

--------------------------------

### Preview a script with dictionary highlighting

Source: https://github.com/aflr-archive/apiaudio-python/blob/main/README.md

Generate a preview of a script with dictionary highlighting applied. This requires a script ID and a voice to be specified. The script text can contain special tags for highlighting.

```python
text = "
      The author of this repo has lived in two places in the
      UK, <!location>Bude<!> and <!location>Bristol<!>.
    "

  r = apiaudio.Script.create(scriptText=text)
  scriptId = r["scriptId"]

  preview = apiaudio.Script.preview(scriptId=scriptId, language="en-gb")
```

--------------------------------

### Mastering.create

Source: https://github.com/aflr-archive/apiaudio-python/blob/main/README.md

Creates a mastered audio file based on a script and various customization options.

```APIDOC
## Mastering.create

### Description
Creates a mastered audio file based on a script and various customization options.

### Method
POST

### Endpoint
/mastering

### Parameters
#### Request Body
- **scriptId** (string) - Required - The script resource ID.
- **version** (string) - Optional - The version of the script to be produced. Default is "".
- **soundTemplate** (string) - Optional - The sound template name. For the list of available sound templates check `apiaudio.Sound.list_sound_templates()` call.
- **public** (boolean) - Optional - Boolean flag that allows to store the mastered file in a public s3 folder. Default value is `False`. Warning - This will cause your mastered files to be public to anyone in the internet. Use this at your own risk.
- **vast** (boolean) - Optional - Boolean flag that allows to create a VAST file of your mastered file. The `vast` flag only works if `public` is `True`. Default value is `False`.
- **endFormat** (list) - Optional - List of audio formats to be produced. Valid formats are: `["wav", "mp3" (default), "flac", "ogg", "mp3_very_low", "mp3_low", "mp3_medium", "mp3_high", "mp3_very_high", "mp3_alexa"]`
- **forceLength** (int) - Optional - Force the audio length of the mastered track (in seconds).
- **audience** (dict) - Optional - Dictionary containing the personalisation parameters. This parameter depends on the number of parameters you used in your [script](#script) resource. If audience is not provided, the fallback track will be created.
- **mediaFiles** (list) - Optional - List of dicts containing the media files. This parameter depends on the media file tags used in the [script](#script) resource and the media files you have in your account.
- **mediaVolumeTrim** (float) - Optional - Floating point variable that allows you to trim the volume of uploaded media files (in dB). This attribute has a valid range of -12 to 12 dB and applies to all media files included in a single mastering call. Clipping protection is not provided so only make incremental adjustments.
- **connectors** (list) - Optional - List of dicts specifying configuration for particular 3rd party connection. For guidelines in context of supported 3rd party application, see [connectors documentation](https://docs.api.audio/docs/what-are-connectors).
- **masteringPreset** (string) - Optional - The mastering preset to use, this enables features such as sidechain compression 'i.e. ducking' See `apiaudio.Mastering.list_presets()` for a list of presets and their descriptions.
- **share** (boolean) - Optional - If you would like to have a sharable link created with your audio file, use this flag. If you put `share: True` the response will have `shareUrl` parameter returned. (Note: If you put this flag, your private files will be converted to public files.)

### Request Example
```python
response = apiaudio.Mastering.create(
    scriptId="id-1234",
    soundTemplate="jakarta",
    audience={"username":"salih", "location":"barcelona"}
)
```

### Response
#### Success Response (200)
- **shareUrl** (string) - URL of the shared mastered audio file (only if `share` is True).

```

--------------------------------

### Mastering.create_media_timeline

Source: https://github.com/aflr-archive/apiaudio-python/blob/main/README.md

Creates a mastering request based purely on uploaded media files.

```APIDOC
## Mastering.create_media_timeline

### Description
Creates a mastering request based purely on uploaded media files. Media files will need to be uploaded before calling this function. See [media](#media).

### Method
POST

### Endpoint
/mastering/timeline

### Parameters
#### Request Body
- **timeline** (list) - Required - The timeline object. A timeline object is a list of dictionaries, whereby each represents a track of audio files. Each track must have the following two keys `files` and `contentType`.
  - **files** (list) - Required - Files is a list of dictionaries, whereby each entry must have the following 3 keys, `mediaId`, `startAt` and `endAt`
    - **mediaId** (str) - Required - the mediaId of the file that has been uploaded.
    - **startAt** (float) - Required - the time that this media file should start at in seconds.
    - **endAt** (float) - Required - the time that this media file should end at in seconds.
  - **contentType** (string) - Required - The type of content that this track contains, should be either `sound` or `speech`
- **endFormat** (list) - Optional - List of audio formats to be produced. Valid formats are: `["wav", "mp3" (default), "flac", "ogg", "mp3_very_low", "mp3_low", "mp3_medium", "mp3_high", "mp3_very_high", "mp3_alexa"]`
- **masteringPreset** (string) - Optional - The mastering preset to use, this enables features such as sidechain compression 'i.e. ducking' See `apiaudio.Mastering.list_presets()` for a list of presets and their descriptions.

### Request Example
```python
backgroundId = apiaudio.Media.upload(file_path="background.wav")["mediaId"]
speechId = apiaudio.Media.upload(file_path="speech1.wav")["mediaId"]

response = apiaudio.Mastering.create_media_timeline(
    timeline=[
        {
            "files": [
                {"mediaId": backgroundId, "startAt": 0.0, "endAt": 10.0}
            ],
            "contentType": "sound"
        },
        {
            "files": [
                {"mediaId": speechId, "startAt": 0.5, "endAt": 5.5}
            ],
            "contentType": "speech"
        }
    ]
)
```
```

--------------------------------

### Create Mastering Request with Callback URL

Source: https://github.com/aflr-archive/apiaudio-python/blob/main/CHANGELOG.md

Use this to create a long-running mastering request and specify a callback URL for notifications.

```python
apiaudio.Mastering().create(scriptId=script_id, callback_url='call-based callback url')
```

--------------------------------

### Create Mastered Audio Timeline

Source: https://github.com/aflr-archive/apiaudio-python/blob/main/CHANGELOG.md

Upload background and speech audio files, then create a mastered audio timeline using a specified mastering preset. This is useful for enhancing existing audio files with a mastering chain or using FFMpeg in the cloud.

```python
backgroundId = apiaudio.Media.upload(file_path="background.wav")["mediaId"]
speechId = apiaudio.Media.upload(file_path="speech1.wav")["mediaId"]

timeline = [
  {
      "files" : [
          {
              "mediaId" : speechId,
              "startAt" : 2,
              "endAt" : 14,
          }
      ],
      "contentType" : "speech"
  },
  {

      "files" : [
          {
              "mediaId" : backgroundId,
              "startAt" : 0,
              "endAt" : 45,
          }
      ],
      "contentType" : "sound"
  }
]
response = apiaudio.Mastering.create_media_timeline(timeline=timeline, masteringPreset="lightducking")
```

--------------------------------

### Script.Directory.list_projects

Source: https://github.com/aflr-archive/apiaudio-python/blob/main/README.md

Lists all projects available in the script directory.

```APIDOC
## Script.Directory.list_projects

### Description
Lists all projects.

### Method
GET (assumed, based on retrieval action)

### Endpoint
`/script/directory/projects` (assumed, based on function name and purpose)

### Parameters
#### Path Parameters
- None

### Request Example
```python
projects = apiaudio.Script.Directory.list_projects()
print(projects)
```

### Response
#### Success Response (200)
- **projects** (list of strings) - A list of project names.

### Response Example
```json
["projectX", "projectY"]
```
```

--------------------------------

### Share Audio via API

Source: https://github.com/aflr-archive/apiaudio-python/blob/main/CHANGELOG.md

Use this endpoint to share audio, which returns a URL for broader distribution.

```shell
curl -X POST \
  'https://v1.api.audio/mastering' \
  --header 'x-api-key: API-KEY' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "scriptId": "xx",
    "share": true
}'
```

--------------------------------

### Create a Script from Text

Source: https://github.com/aflr-archive/apiaudio-python/blob/main/README.md

Create a new script asset by providing the text content. The scriptId is returned upon successful creation.

```python
script = apiaudio.Script.create(scriptText="Hello world")
print(script)
```

--------------------------------

### Mastering.create_media_timeline

Source: https://github.com/aflr-archive/apiaudio-python/blob/main/README.md

Creates a mastered media timeline based on the provided timeline configuration and mastering preset.

```APIDOC
## Mastering.create_media_timeline

### Description
Creates a mastered media timeline. This method takes a timeline structure and a mastering preset to generate the mastered audio.

### Method
POST (inferred from SDK usage)

### Endpoint
/v1/mastering/timeline (inferred from SDK usage)

### Parameters
#### Request Body
- **timeline** (list) - Required - A list of objects defining the media files, their start and end times, and content type.
- **masteringPreset** (string) - Required - The name of the mastering preset to apply (e.g., "lightducking").
```

--------------------------------

### Create Speech with Section-Specific Configurations

Source: https://github.com/aflr-archive/apiaudio-python/blob/main/README.md

Creates a speech audio file from a script, allowing for different voice, speed, and effects configurations for specific sections.

```python
sections={
    "firstsection": {
        "voice": "Matthew",
        "speed": 110,
        "silence_padding": 100
    },
    "anothersection": {
        "voice": "en-GB-RyanNeural",
        "speed": 100
    }
}
```

--------------------------------

### List Available Mastering Presets

Source: https://github.com/aflr-archive/apiaudio-python/blob/main/README.md

Retrieve a list of all available mastering presets. No parameters are required for this operation.

```python
presets = apiaudio.Mastering.list_presets()
print(presets)
```

--------------------------------

### List Media Files with Download URL

Source: https://github.com/aflr-archive/apiaudio-python/blob/main/README.md

Retrieves a list of media files, including a presigned download URL for each. Note that this can be slow for a large number of files.

```python
# lists files with tag="tag1" and with a downloadurl
files = apiaudio.Media.list(tags="tag1", downloadUrl=True)
```

--------------------------------

### List Media Files by Tag

Source: https://github.com/aflr-archive/apiaudio-python/blob/main/README.md

Retrieves a list of media files that match the specified tags. This is useful for organizing and finding specific files.

```python
# lists files with tag="tag1"
files = apiaudio.Media.list(tags="tag1")
```

--------------------------------

### Speech.create

Source: https://github.com/aflr-archive/apiaudio-python/blob/main/README.md

Creates a speech audio file from a script. Supports various parameters for voice, speed, effects, and personalization.

```APIDOC
## Speech.create

### Description
Creates a speech audio file from a script. Supports various parameters for voice, speed, effects, and personalization.

### Method
POST (inferred from SDK method)

### Endpoint
/speech (inferred from SDK resource)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **scriptId** (string) - Required - The ID of the script to use.
- **version** (string) - Optional - The version of the script.
- **voice** (string) - Optional - The voice to use for the speech.
- **speed** (integer) - Optional - The speed of the speech.
- **effect** (string) - Optional - An audio effect to apply.
- **silencePadding** (integer) - Optional - Padding in milliseconds for silence.
- **sync** (boolean) - Optional - Whether to synchronize speech generation.
- **audience** (dict) - Optional - Personalization parameters for the audience.
- **sections** (dict) - Optional - Configuration for specific sections of the script.

### Request Example
```json
{
  "scriptId": "id-1234",
  "version": "abc",
  "voice": "Matthew",
  "speed": 100,
  "effect": "dark_father",
  "silencePadding": 1000,
  "sync": true,
  "audience": {"username": "Elon", "lastname": "Musk"},
  "sections": {
    "firstsection": {"voice": "Matthew", "speed": 110, "silence_padding": 100},
    "anothersection": {"voice": "Liam"}
  }
}
```

### Response
#### Success Response (200)
- **audio_url** (string) - URL to the generated speech file.

#### Response Example
```json
{
  "audio_url": "http://example.com/speech.mp3"
}
```
```

--------------------------------

### Create a Mastered Audio File

Source: https://github.com/aflr-archive/apiaudio-python/blob/main/README.md

Use this method to create a mastered audio file from a script. You can specify script ID, sound template, and audience personalization parameters. Ensure the scriptId is provided.

```python
response = apiaudio.Mastering.create(
    scriptId="id-1234",
    soundTemplate="jakarta",
    audience={"username":"salih", "location":"barcelona"}
)
```

--------------------------------

### Script.Directory.list_modules

Source: https://github.com/aflr-archive/apiaudio-python/blob/main/README.md

Lists all modules within a given project prefix.

```APIDOC
## Script.Directory.list_modules

### Description
Lists all modules within a projectPrefix.

### Method
GET (assumed, based on retrieval action)

### Endpoint
`/script/directory/modules` (assumed, based on function name and purpose)

### Parameters
#### Query Parameters
- **projectPrefix** (string) - Required - Will list modules starting with this projectPrefix.

### Request Example
```python
modules = apiaudio.Script.Directory.list_modules(projectPrefix="workout")
print(modules)
```

### Response
#### Success Response (200)
- **modules** (list of strings) - A list of module names matching the project prefix.

### Response Example
```json
["workout_1/over60s", "workout_2/morning_routine"]
```
```

--------------------------------

### SyncTTS.create

Source: https://github.com/aflr-archive/apiaudio-python/blob/main/README.md

Create a Synchronous Text-To-Speech (TTS) audio file using a specified voice and text. Supports optional metadata for phoneme lists.

```APIDOC
## SyncTTS.create

### Description
Create a Synchronous Text-To-Speech (TTS) audio file using a specified voice and text. Supports optional metadata for phoneme lists.

### Method
POST (inferred)

### Endpoint
/synctts (inferred)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **voice** (string) - Required - The voice name. See the list of available voices using [Voice resource](#voice).
- **text** (string) - Required - The text you want to do TTS with. The limit is 800 characters for wave files.
- **metadata** (string) - Optional - ("full" or "none") - The level of metadata you want. Returns phoneme lists (only available for some msnr voices).

### Request Example
```python
sync_tts = apiaudio.SyncTTS.create(
  voice="joanna",
  text="This is me creating synchronous text to speech",
  metadata="full"
)
```

### Response
#### Success Response (200)
- **audio_content** (bytes) - Wave bytes ready to be played or written to a file.

#### Response Example
(Not provided in source)
```

--------------------------------

### SyncTTS with Metadata

Source: https://github.com/aflr-archive/apiaudio-python/blob/main/CHANGELOG.md

Use `metadata=True` with `syncTTS` to generate a URL for the audio data. The response includes audio data, URL, sampling rate, and event data.

```python
response = apiaudio.SyncTTS.create(text="Hello", voice="shelly", metadata=True)
```

```json
{
    "audio_data": string, # base64 encoded
    "url": string,
    "sampling_rate": string,
    "event_data": [
        {
            "phoneme": string,
            "viseme": string,
            "offset": float,
            "duration": float
        }
    ]
}
```

--------------------------------

### List All Available Sound Templates

Source: https://github.com/aflr-archive/apiaudio-python/blob/main/README.md

Retrieves a list of all available sound templates from the API. Parameters are optional and can be used to filter for specific sound characteristics.

```python
sound_templates = apiaudio.Sound.list()
```

--------------------------------

### Orchestrator.create_audio()

Source: https://github.com/aflr-archive/apiaudio-python/blob/main/README.md

Creates a simple Text-to-Speech (TTS) speech request and adds a sound template to it through mastering.

```APIDOC
## Orchestrator.create_audio()

### Description
Creates a simple Text-to-Speech (TTS) speech request and adds a sound template to it through mastering.

### Method
create_audio()

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **scriptText** (str) - Required - Text to synthesize (TTS).
- **soundTemplate** (str) - Optional - Sound template to use.
- **voice** (str) - Required - Name of voice to use.

### Request Example
```python
apiaudio.Orchestrator.create_audio(
  scriptText="Hello, this is a test.",
  voice="en-US-Standard-C",
  soundTemplate="default"
)
```

### Response
#### Success Response (200)
- **audio_id** (string) - The ID of the created audio.
- **status** (string) - The status of the audio creation process.

#### Response Example
```json
{
  "audio_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "status": "processing"
}
```
```

--------------------------------

### Set API Key for Authentication

Source: https://github.com/aflr-archive/apiaudio-python/blob/main/README.md

Configure the SDK with your secret API key obtained from the Aflorithmic Dashboard. This is required for authenticating your requests.

```python
apiaudio.api_key = "your-key"
```

--------------------------------

### List Sound Parameters

Source: https://github.com/aflr-archive/apiaudio-python/blob/main/README.md

Retrieves the available attributes and their allowed values for filtering sound templates. Use this to understand filtering options before listing sound templates.

```python
parameters = apiaudio.Sound.list_parameters()
```

--------------------------------

### Script.list()

Source: https://github.com/aflr-archive/apiaudio-python/blob/main/README.md

Lists all scripts available in the organization, with support for filtering by project name, module name, script name, and script ID. Can return verbose details or a summary.

```APIDOC
## Script.list()

### Description
Lists all scripts available in the organization, with support for filtering by project name, module name, script name, and script ID. Can return verbose details or a summary.

### Method
```python
apiaudio.Script.list(
    projectName: str = None,
    moduleName: str = None,
    scriptName: str = None,
    scriptId: str = None,
    verbose: bool = True
)
```

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **projectName** (string) - Optional - Return any scripts with this projectName.
- **moduleName** (string) - Optional - Return any scripts with this moduleName, note `projectName` also needs to be supplied.
- **scriptName** (string) - Optional - Return any scripts with this scriptName, note both `projectName` and `moduleName` need to be supplied.
- **scriptId** (string) - Optional - Return any scripts with this scriptId.
- **verbose** (bool) - Optional - List scripts in verbose mode (`True` by default). Set this to `False` to return only the `projectName`, `moduleName`, `scriptName` and `scriptId` fields.

### Request Example
```python
scripts = apiaudio.Script.list()
```

### Response
#### Success Response (200)
A list of scripts matching the specified filters.

#### Response Example
```json
[
  {
    "scriptId": "id-1234",
    "scriptName": "myScript",
    "projectName": "myProject",
    "moduleName": "myModule"
  }
]
```
```

--------------------------------

### Script.Directory.list_script_names

Source: https://github.com/aflr-archive/apiaudio-python/blob/main/README.md

Lists all script names within a given project and module prefix.

```APIDOC
## Script.Directory.list_script_names

### Description
Lists all script names within a projectPrefix and modulePrefix.

### Method
GET (assumed, based on retrieval action)

### Endpoint
`/script/directory/scriptNames` (assumed, based on function name and purpose)

### Parameters
#### Query Parameters
- **projectPrefix** (string) - Required - Will list scriptNames starting with this projectPrefix.
- **modulePrefix** (string) - Required - Will list scriptNames starting with this modulePrefix.

### Request Example
```python
scriptNames = apiaudio.Script.Directory.list_script_names(projectPrefix="workout_1", modulePrefix="over60s")
print(scriptNames)
```

### Response
#### Success Response (200)
- **scriptNames** (list of strings) - A list of script names matching the provided prefixes.

### Response Example
```json
["workout_1/over60s/routine_1", "workout_1/over60s/routine_2", "workout_1/over60s/routine_3"]
```
```

--------------------------------

### List Media File by ID

Source: https://github.com/aflr-archive/apiaudio-python/blob/main/README.md

Retrieves a specific media file by its unique ID. If the ID does not exist, an empty object is returned.

```python
# lists file with specific id
files = apiaudio.Media.list(mediaId="some_mediaId")
```

--------------------------------

### Create Media Timeline Request

Source: https://github.com/aflr-archive/apiaudio-python/blob/main/README.md

This method creates a mastering request using uploaded media files. Media files must be uploaded prior to calling this function. The timeline parameter defines the structure and timing of audio tracks.

```python
backgroundId = apiaudio.Media.upload(file_path="background.wav")["mediaId"]
speechId = apiaudio.Media.upload(file_path="speech1.wav")["mediaId"]
```

--------------------------------

### Create Audio with Alexa Preset

Source: https://github.com/aflr-archive/apiaudio-python/blob/main/CHANGELOG.md

Use the `endFormat` parameter to specify presets like `mp3_alexa` for targeted audio formatting.

```python
m = apiaudio.Mastering().create(scriptId=GLOBAL_SCRIPT_ID, endFormat="mp3_alexa")
```