Custom Sound Templates

As well as AudioStack's provided sound templates, you can upload your own custom sound design.

In this guide we will look at how to upload a custom sound template containing your own sound design.

A sound template contains two distinct components, metadata and segments.

Metadata simply put is metadata detailing the style, genre, tags and description of the sound template.

Segments are the audio file components of a sound template object. A template can contain many sound segments, in our own library they usually have 3, intro, main, and outro. These names are only used as symbolic placeholders , you might wish to name yours differently.

Creating a template

To create a template we must first register a new template.

Python

template = audiostack.Production.Sound.Template.create(templateName="example") 

🚧

Templates must be uniquely named. Use the following line of code to delete a template and all of its segments.

Python

> 🚧 audiostack.Production.Sound.Template.delete(templateName="example")

Uploading sound segments

Uploading a sound segment is a two step process. First we need to upload our sound segment to the file service, and then we make a second api call to register this file as a sound segment. In the example below we upload our a file named main.wav and this becomes our main soundSegment

Python

# Upload each segment of our template to audiostack media storage and assign it to the template previously created
# add to media storage
response = audiostack.Content.File.create(localPath=soundtemplatepath, uploadPath="main.wav", fileType="audio")                


# assign to our template
response = audiostack.Production.Sound.Segment.create(             
    templateName=soundtemplatename, soundSegmentName="main", mediaId=response.fileId
) 

To upload another sound segment the above process should be repeated.

Testing

To test our sound template lets make an end-to-end production request.

Python

script = audiostack.Content.Script.create(
    scriptText="""<as:section name="main" soundSegment="main">  Hello world! </as:section>"""
)

speech = audiostack.Speech.TTS.create(scriptItem=script)

mix = audiostack.Production.Mix.create(
    speechItem=speech,
    soundTemplate="example",
)

mix.download()

Text

🚧

The soundSegment field in the script must match a valid soundSegment name

The following markup in the script <as:section name="main" soundSegment="main">will play the sound segment main from your supplied sound template. An error is throw in the Mix endpoint if your template does not have a named soundSegment.

Code Example

Copy and paste the below example to get started with an example - you'll just need to fill in the required fields and save the audio file needed on your machine in the same folder as your code.

Python

import audiostack
import os


audiostack.api_key = "APIKEY" # Add your API Key here

soundtemplatename = "soundtemplate1" # rename me
soundtemplatepath = "filename.wav" # rename me
scriptname = "name" # rename me

script = """
    <as:section name="main" soundsegment="main"> This is where the text of your script goes.
    </as:section>

"""

# Run me once, if you get errors run me again- this just means a template with that name already existed.
try:
    template = audiostack.Production.Sound.Template.create(templateName=soundtemplatename) 
except Exception as e:
    response = audiostack.Production.Sound.Template.delete(templateName=soundtemplatename)
    raise ValueError("template already existed so we cleared it for you, just re-run the demo")


# Upload each segment of our template to audiostack media storage and assign it to the template previously created
# add to media storage
response = audiostack.Content.File.create(localPath=soundtemplatepath, uploadPath="main.wav", fileType="audio")                


# Assign to our template
response = audiostack.Production.Sound.Segment.create(             
    templateName=soundtemplatename, soundSegmentName="main", mediaId=response.fileId
) 

print("content uploaded")

# 3. Template created! Now lets make use of it:
script = audiostack.Content.Script.create(scriptText=script, scriptName=scriptname, projectName="demo1")        
speech = audiostack.Speech.TTS.create(
        scriptItem=script,
        voice="wren",
        speed=1,
)
mix = audiostack.Production.Mix.create(
    speechId=speech.speechId,
    soundTemplate=soundtemplatename,
    masteringPreset="balanced",
)
encoded = audiostack.Delivery.Encoder.encode_mix(
    productionItem=mix,
    preset='wav',
    loudnessPreset = 'spotify'
)
encoded.download(fileName=f"{soundtemplatename}_{scriptname}")
print("Downloaded -> ", encoded.data)