Time & Length Alignment Feature Guide

Force Length Features allows you to adjust the length of each of your script sections. This comes in handy when your audio files must adhere to a time limit. For example you could be creating audio to fit over your video file - for that it is important that the intro fits in the first 10 seconds, the main section ends at 40 seconds and the last 20 seconds are dedicated for the outro.

How to use force length feature

To use force section length we defined a new mastering parameter called sectionProperties. This takes a dict as its input, whereby each key has the name of the section and its value is another dict with the properties corresponding to that section. We currently support two properties per section:

EndAt: (float) the time in seconds that this section should end at
Justify: (text) [optional] how the audio content of this section should be justified.

sectionProperties = {
'first': {'endAt': 10, 'justify': 'flex-start'}, 
'second': {'endAt': 20, 'justify': 'flex-end'}, 
}
mastering = apiaudio.Mastering.create(scriptId=scriptId,soundTemplate=soundTemplate, sectionProperties=sectionProperties)

📘

Remember that the key of each section must correspond to section names defined in the script

text = """
<<soundSegment::intro>><<sectionName::first>> Hello world and welcome to API dot audio.
<<soundSegment::intro>><<sectionName::second>> Lets force the section length.
"""
script = apiaudio.Script.create(scriptText=text)

❗️

Justify can only be used when forcing a section length

Properties

EndAt
End at forces a section to end at a given time in seconds. This is optional and can be applied to any section. Sections without a forced length will play as normal. Each section must be a minimum of 2 seconds in length.

Justify
Justify is an optional parameter that determines how the speech/effect/media within a section are sequenced. This is useful for when the combined length of speech/effect/media is less than the specified endAt value. There are 3 options:

• Flex-start (default): any gap between speech/effect/media ending and the next section starting is placed at the end of the current section. Speech will start at the very beginning together with the sound.
• Flex-end: The gap is placed at the start of the current section. Speech is pushed to the end of the section, with sound starting at the beginning.
• Centre: Gaps are placed evenly at the start and end of the current section. Speech will float in the middle of the section.

If the section is longer than the endAt value (i.e. the section is too long), the section will be trimmed from the end, the justify value is ignored, and a warning is returned from the API call.

Examples

1.✍️ First lets create a script text and define the section names

text="""
<<soundSegment::intro>><<sectionName::first>> Hello world and welcome to API audio.
<<soundSegment::intro>><<sectionName::second>> Lets force the section length.
"""
script = apiaudio.Script.create(scriptText=text)

2.⬇️ Define the section properties for both of your sections. In this case we want each of the sections to be 10 seconds in length.

The first section will end at 10 seconds and will be justified to the start of the section. The second section will end at 20 seconds and the speech will be justified to float at the centre of the section.

This makes the total length of the audio file in this case to be 20 seconds.

sectionProperties = {
'first': {'endAt': 10, 'justify': 'flex-start'}, 
'second': {'endAt': 20, 'justify': 'centre'}, 
}

Let's look at more examples of defining section properties:

• The first section will be 10 seconds long, and the second will be as long as required to play all speech/effect/media

sectionProperties = {
'first': {'endAt': 10, 'justify': 'flex-start'}, 
}

The first section will be as long as required to play all speech/effect/media as long as the length of the first and second sections are less than 20. Content is always cut in reverse order (i.e. section 2 first)

sectionProperties = {
'second': {'endAt': 20, 'justify': 'flex-start'}, 
}

The first section will be 20 seconds long, there will be delay in the speech being played as section 1 will end just before section 2 starts. As section 2 is flex-start, this gives a near-perfect transition at the 20 second mark.

sectionProperties = {
'first': {'endAt': 20, 'justify': 'flex-end'}, 
'second': {'endAt': 30, 'justify': 'flex-start'}, 
}

End-to-end Example

import apiaudio
apiaudio.api_key ="API_KEY"


text = """
<<soundSegment::intro>><<sectionName::first>> Hello world and welcome to API dot audio. 
<<soundSegment::main>><<sectionName::second>> Lets force the section length.
"""

sectionProperties = {
'first': {'endAt': 5, 'justify': 'flex-start'}, 
'second': {'endAt': 10, 'justify': 'centre'}, 
}


script = apiaudio.Script().create(
    scriptText=text, scriptName="hi"
)

r = apiaudio.Speech().create(
    scriptId=script.get("scriptId"),
    voice="linda", 
    speed=100,
)

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


print(response)

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