API reference

This chapter contains the API reference for the dramatts.core and dramatts.voices modules.

ScriptParser

class dramatts.core.ScriptParser(input_file=None, start_line=0, end_line=None, substitutions=None)

A parser to identify content types inside a text file

Parameters:
  • input_file (pathlib.Path) – Path to text file
  • start_line (int) – First line to import
  • end_line (int) – Last line to import - None means last line of text file
  • substitutions (list) – A list of text substitutions - details see Attributes
filename

Path to text file

Type:pathlib.Path
start_line

First line to import

Type:int
end_line

Last line to import - if None last line of text file

Type:int
substitutions

A list of dictionaries with keys:

  • ‘search_text’(str): Text or RegEx pattern to search for
  • ‘subst’(str): Replacement text
  • ‘regex’(bool): If true - assume ‘search_text’ is a RegEx
  • ‘comment’(str): Additional information on this substitution
Type:list
text

Raw text of the imported file

Type:str
characters

List of characters in the play

Type:list
lines_list

List of dictionaries for each line/paragraph identified in the text - dict keys:

  • ‘start’(int): index of first character inside the text
  • ‘end’(int): index of last character inside the text
  • ‘content’(str): Content of the line/paragraph
  • ‘content_type’(str):
    • ‘SceneTitle’,
    • ‘DialogueIndicator’,
    • ‘DialogueContent’,
    • ‘InlineComment’
    • ‘NarrativeDescription’
  • ‘speaker’(str): Name of speaker for this line - e.g. a character’s name
Type:list
content_identifiers

List of dictionaries - for each content identifier with keys:

  • ‘name’(str): Name of the identifier
  • ‘pattern’(str): RegEx pattern
  • ‘info’(str): Explantation of the content identifier
  • ‘example’(str): An example matching the pattern
Type:list
ident_assigments

Assignment of different identifier types to a content identifier - valid keys are: ‘SceneTitle’, ‘Dialogue’, ‘SpeakerName’ and ‘InlineComment’ - the value must be a content identifier dictionary (e.g. an element of the content_identifiers list)

Type:dict
check_content_identifiers()

Checks the content identifiers patterns vs. the example

Returns:True if example matches pattern
Return type:bool
export_identifiers(filename)

Exports the content identifiers

export_parsed_lines(filename)

Exports the parsed lines

export_substitutions(filename)

Exports the substitutions

get_characters_from_parsed_lines()

Gets characters list from parsed lines and assign it to the characters attribute

Returns:None
get_filtered_valid_lines(first_scene=0, last_scene=None, speaker=None)

Filters the valid_lines_list acc. to scene range and speaker name

Parameters:
  • first_scene (int) – Start scene
  • last_scene (int) – End scene - if None the last scene of the play will be assumed
  • speaker (str) – Name of speaker to limit filter to
Returns:

List of dicts - same format as valid_lines_list, but filtered to scene range and/or speaker
Return type:

list
get_lines_per_character()

Counts the lines/paragraphs for each speaker

Returns:key = character name - value = no. of lines, sorted by the number by line count (descending)
Return type:dict
identifier_names

Returns a list of available identifier names

Type:list
import_identifiers(filename)

Imports the list of content identifiers from a file

import_parsed_lines(filename)

Imports parsed lines from json

import_substitutions(filename)

Imports the list of substitutions from a file

parse_lines(filename=None)

Parses the specified text file and assign result to lines_list attribute

Parameters:filename (pathlib.Path) – Path to textfile, if None the filename attribute will be used (if defined)
Returns:The value of the lines_list attribute
Return type:list
scene_count

Number of scenes in the script

Type:int
scenes_titles

List of the scene titles

Type:list
substiute_text(text)

Substitutes elements in text (supports regex as defined by python re module)

Parameters:text (str) – Text to check/modify
Returns:Modified text
Return type:str
valid_lines_list

Only non-empty lines/paragraphs of the lines_list attribute

Note

Has additional key-value pairs cmp. lines_list:

  • ‘scene_no’(int): Scene the line/paragraph belongs to
  • ‘scene_line_no’(int): Line number inside the side (where 0 is always the SceneTitle).
Type:list

AudioRenderer

class dramatts.core.AudioRenderer(voices=None, cpu_threads=4)

This class provides configuration of the audio rendering and wrappers to launch the external tools (festival, sox) with predefined parameters for speech synthesis and post-processing

Parameters:
  • voices (dict) – Dictionary with key = speaker name, value is a VoiceConfig object
  • cpu_threads (int) – Number of parallel CPU threads to use for rendering
voices

Dictionary with key = speaker name, value is a VoiceConfig object

Type:dict
cpu_threads

Number of parallel CPU threads to use for rendering

Type:int
norm_level

DB level to use for normalizing audio

Type:int
sox_path

Path to the SoX application

Type:pathlib.Path
festival_path

Path to the festival application

Type:pathlib.Path
festival_client_path

Path to the festival_client application

Type:pathlib.Path
text2wave_path

Path to the text2wave script

Type:pathlib.Path
installed_festival_voices

List of voice names installed for festival

Type:list
external_tools

A dictionary with the configuration setting for the external tools - keys: ‘festival’, ‘festival_client’, ‘sox’ and ‘text2wave’. Each tool’s key holds another dictionary with the keys:

  • ‘path’(pathlib.Path): Path to application
  • ‘version’(str): Version string
  • ‘installed’(bool): True if the tool was found to be working
Type:dict
use_festival_server

True if server should be used instead of local render via text2wave

Type:bool
festival_server_name

Hostname or IP-Address of the festival server

Type:str
festival_server_port

Port number of the server

Type:int
invalid_voices

List of speaker names with invalid configuration (e.g. defined festival voices not installed) - a dict for each invalid speaker with keys:

  • ‘name’(str): Name of the speaker
  • ‘index’(int): Position of the speaker in the voices attribute
  • ‘params’(list): A list of invalid parameter names - e.g. [‘voice_name’]
Type:list
check_component(path, tool_name, test_args, answer_str, answer_version=False)

Checks an individual external tool by invoking the tool with defined test arguments and validating against an expected answer

Parameters:
  • path (pathlib.Path) – Path to executable (incl. executable name)
  • tool_name (str) – Name of tool
  • test_args (tuple) – Command line arguments to use for functions test (e.g. to get version string)
  • answer_str (str) – A required str in the answer of the command line invocation with test_args
  • answer_version (bool) – Extract version str form
Returns:

with keys: path, version and installed.
Return type:

dict
check_installed_components()

Checks if external components are installed and updates the external_tools attribute

Returns: None

check_voices()
Checks the voice parameters for correctness (e.g. voice installed) and assigns invalid voices
to the invalid_voices attribute
Returns:List of dicts with speaker name, index and invalid parameter in self.voices
Return type:list
create_voices_dict()

Create a dictionary with all voices

export_voices(filename)

Exports all voices to a json file

static get_ext_tool_path(exec_name)

Get path to external executable

Parameters:exec_name (str) – Name of the application/executable
Returns:Path to executable if found - else None
Return type:str
get_festvial_voices()

list: List of the installed festival voices (str)

static get_tool_feedback(command_name, path=None, cmd_args=('--version', ))

Calls an external tool with certain arguments and returns feedback (for testing functionality)

Parameters:
  • command_name (str) – Name of command to check
  • path (pathlib.Path) – Path to the executable, if None see below
  • cmd_args (tuple) – Command line arguments to pass to tool

Note

If path is none the command will be invoked only with the commnand_name - assuming the executable’s location is added to the PATH environment variable.

import_voices(filename)

Imports voices from a json file

play_audio_test(voice, text)

Plays a test text for the current voice

Parameters:
  • voice (VoiceConfig) – voice configuration
  • text (str) – Text for testing
read_voices_dict(voices_dict)

Fills voices attribute dict with VoiceConfig objects defined by values from a dictionary

Parameters:voices_dict (dict) – Dictionary with key for each speaker name. Each speaker key holds another dictionary with voice parameters with following keys: - ‘voice_name’(str): Festival voice name - ‘user_pitch_shift’(int): Pitch shift offset - ‘user_tempo’(float): Tempo factor - ‘user_volume’(float): Volume factor
render_audio(voice, text, filename, normalize=False)

Renders a specific script line (or part of a line) into an audio file

Parameters:
  • voice (str) – Name of speaker
  • text (str) – Text to render
  • filename (pathlib.Path) – Path object
  • normalize (bool) – If true normalize the sound level

ProjectManager

class dramatts.core.ProjectManager(script_parser, audio_renderer, output_folder=None)

Manager for a dramaTTS session

Parameters:
  • script_parser (ScriptParser) – ScriptParser object
  • audio_renderer (AudioRenderer) – AudioRenderer object
  • output_folder (pathlib.Path) – Folder for the generated audio files
project_filepath

Path to the project file

Type:pathlib.Path
script_parser

ScriptParser object

Type:ScriptParser
audio_renderer

AudioRenderer object

Type:AudioRenderer
output_folder

Folder for the generated audio files

Type:pathlib.Path
speaker_to_render

Speaker name, if output for a specific speaker only shall be rendered (otherwise None)

Type:str
normalize

If true the audio output will be normalized

Type:bool
combine

If true the files for the individual scenes will be combined to single file too

Type:bool
start_scene

First scene to render

Type:int
end_scene

Last scene to render - if None the last scene in the play will be assumed

Type:int
digits_scene_no

Number of digits for zero padding in the scene folders/file names

Type:int
digits_line_no

Number of digist for zero padding of the line numbers in the wave files

Type:int
preferences

Dictonary to store the program preferences - see create_prefs_dict method for details

Type:dict
add_speakers_for_characters()

Adds default speaker for each character found by the script parser, who does not alerady have a speaker assigned

combine_audio(input_path=None, output_path=None)

Merges all files in one directory (excluding subdirs) into a single file

Parameters:
  • input_path (pathlib.Path) – Folder name of files to combine (defaults to output_folder)
  • output_path (pathlib.Path) – Filename of combined file (defaults to output_folder + .wav)
convert_speaker_to_comment(speaker_name, from_prefix='\n', from_suffix='\n', to_prefix='\n(', to_suffix='\n)')

Deletes and entry in the speakers dictionary and creates a substitution adding prefixes and suffixes

Parameters:
  • from_prefix (str) – Prefix before speaker_name to include in search text
  • from_suffix (str) – Suffix after speaker_name to include in search text
  • to_prefix (str) – Prefix before speaker_name to include in substitution
  • to_suffix (str) – Suffix after speaker_name to include in subsitution

Notes

  • This is useful, if the parser misunderstood director instructions for speaker names (DialogueIndicator)
create_prefs_dict()

dict: Creates a dictionary with the preferences settings

create_project_dict()

dict: Creates a dictionary representation of the current project settings

default_config_path

Default config path

Type:pathlib.Path
get_line_no_str(line_no)

str: Returns a string representation of the line number

get_scene_folder_path(scene_no)

pathlib.Path: Returns the path to a scene subfolder

get_scene_no_str(scene_no)

str: Returns a string representation of the scene number

load_preferences(filepath=None)

Loads the preferences from a json file

Parameters:filepath (pathlib.Path) – If none the default config file (see default_config_path property method)
load_project(filepath=None)

Loads a project from a file

Parameters:filepath (pathlib.Path) – path to file name (if None self.project_filepath will be used)
normalize_audio()

Normalizes all audio segments and rebuilds files for each scene

process_prefs_dict(prefs)

Processes the preferences dict (see create_prefs_dict) and assings values to internal variables

process_project_dict(project)

Reads a project dict and assigns to internal variables

render_line_from_dict(line_dict)

Renders a line based on the dictionary provided by the script parser

Parameters:line_dict (dict) – An element of the list returned by ScriptParser.get_filtered_valid_lines method
Returns:Returns the argument
Return type:dict
render_script()

Renders the script into audio files

save_preferences(filepath=None)

Saves the preferences to a json file

Parameters:filepath (pathlib.Path) – If none the default config file will be used (see default_config_path property method)
save_project(filepath=None)

Save the complete project

Parameters:filepath (pathlib.Path) – path to file name (if None self.project_filepath will be used)

Helper functions

dramatts.core.handle_getstatusoutput(commandpath, cmd_args)

Returns the output from subprocess.getstatusoutput taking into account the os.name

Parameters:
  • commandpath (pathlib.Path) – Path to executable including executable name
  • cmd_args (tuple) – Tuple with command line arguments (str) to pass to the programm
dramatts.core.convert_version_string(version_str)

Converts a version string into integer values for major, minor, patch

Parameters:version_str (str) – Version string like ‘1.0.0’ or ‘1.0’
Returns:Tuple of int values (major, minor, patch). Patch will be None, if two digit version_str provided.
Return type:tuple

VoiceConfig

class dramatts.voices.VoiceConfig(voice_name='cmu_us_slt_cg', pitch_shift=0, tempo=1.0, volume=1.0, speaker_name=None)

Creates a voice config that allows changing pitch and tempo of the festival voices

Parameters:
  • voice_name (str) – A festival voice name
  • pitch_shift (int) – SoX pitch shift value (+-100ths of a semitone)
  • tempo (float) – SoX tempo factor (1.0 = no change)
  • volume (float) – Volume factor (1.0 = no change, >1.0 = louder)
create_voice_dict()

Creates a dictionary representation of the voice config

Returns:
Dictionary representation of voice config with keys:
  • ’voice_name’(str): Name of the voice in festival
  • ’user_pitch_shift’(int): Pitch shift in 1/100th of semi-tone
  • ’user_tempo’(float): Tempo factor
  • ’user_volume’(float): Volume factor
Return type:dict
pitch_shift

Final pitch shift

Type:int
tempo

Final tempo

Type:float
update_parameters(voice=None, pitch_shift=0, tempo=1.0, volume=1.0)

Updates the voice parameters

Parameters:
  • voice (str) – Name of the voice in festival
  • pitch_shift (int) – Pitch shift in 1/100th of semi-tone
  • tempo (float) – Tempo factor
  • volume (float) – Volume factor
volume

Final volume

Type:float