Browse
 
Tools
Rss Categories

Speech Tuner Data Export API

Reference Number: AA-02182 Views: 8088 0 Rating/ Voters
Added in 15.1.100

Functionality was introduced with LumenVox version 15.1, which allows users to access and export Response File (.callsre) data using a command line interface.

Historically, the Speech Tuner has been run as a graphical interface based application, and this continues to be the case, however the new Speech Tuner API can be activated by calling the Speech Tuner from a command prompt specifying an optional new .tunerapi file type.


Why use the Data Export API

There are many reasons why users might want to export data from Response File data via the command line, instead of manually exporting the information which is exposed within the Speech Tuner application itself.

The most obvious use-case for this is to provide access to this data to existing business automation systems. By providing a command line interface, this means that batch files, automated scripts, or external applications can call on the Speech Tuner to perform these data exporting operations automatically, or scripted into some other operation or process flow.

All of the data being extracted using this API would also be accessible using the Speech Tuner in the regular GUI invocation, however this requires manual interaction, which cannot readily be automated, therefore this Data Export API method was developed to allow users more convenient access to the data enabling better integration with their own systems, or for whatever other purposes the data would be needed.


Configuration File

To implement this new Speech Tuner Data Export API functionality, a command line parameter filetype needed to be added. This new .tunerapi file will contain all of the information needed for each API request.

Contained within this new configuration text file should be a [TUNERAPI] section header in the first line, followed by a number of parameters that describe the current API request, which are detailed in Table 1, below and each of the parameters are described individually in subsequent sections below.

The order in which the parameters appear is not important, however the first line must contain the [TUNERAPI] section header (see the example further below)

Setting Name

Description

operation

The desired API operation (only data_export is currently supported)

input_filename

Full path to the Response (.callsre) File to be processed within the API request

output_folder

The path to the output folder where data output from the API request will be stored

audio_source

 

A value describing the source of exported ASR audio, which should be one of the following:

  • none = No ASR audio will be exported
  • decoded = Only the decoded (post-processed) audio will be exported
  • loaded = trimmed pre-processed audio will be exported
  • streamed = the entire audio stream will be exported 

audio_filename_prefix

If no logging-tag is detected in the .callsre file, this prefix will be applied to the audio files generated. If neither logging-tag, nor this value is specified, a default prefix of “AudioOutput” will be used.

include_dtmf

If enabled (1) DTMF data will also be exported to the .csv Report File

include_tts_audio

If enabled (1), synthesized TTS audio exported to the target folder

include_no_input

If enabled (1),  NO_INPUT interactions will be processed, otherwise they will be excluded

Table 1 : Data Export API Parameters


Operation

This parameter is used to specify the type of API operation being requested. The only supported operation at this time is data_export. This parameter is designed to allow for additional methods to be developed in future, if needed.


Input Filename

The input_filename parameter describes an individual Response File (.callsre) that should be processed as part of the current API request.

Note:

Please note that an individual Response File may contain a number of different interactions, including SRE, TTS, DTMF and NO_INPUT events. All of these will be processed and exported according to the other parameters specified.

When multiple audio files are included, the resulting audio filenames will include a suffix in the filename to indicate which interaction within the Response File it relates to.


Output Folder

The output_folder specified will be used when exporting data. If this folder is invalid or cannot be written to, the API request will fail.

Within this folder, any exported audio files will be stored, along with a Comma Separated Variable (.csv) format Export Report File will be generated, or appended to if one exists. This file will contain information about the processed data relating to the API request.


Audio Source

There are potentially a number of different types of audio stored within Response Files, depending on the configuration settings that control the generation of Response Files.

For Media Server users, this is the enable_sre_logging setting in the media_server.conf file.

For other users, this is the SAVE_SOUND_FILES value in client_property.conf.

Both of these settings control the level of detail contained within Response Files, including which audio data is stored.

The appropriate audio_source will be used when exporting data, assuming that audio data is available in the file. If it is not, no audio file will be exported.


Audio Filename Prefix

This is used as the default prefix for any audio files generated by this request. Whenever possible, a Logging-Tag will be used as the prefix for any audio files generated, however in the absence of a Logging-Tag, this audio_filename_prefix will be used instead.

If neither Logging-Tag or audio_filename_prefix are specified, the default value of “AudioOutput” will be used.

Typically, audio filenames include some prefix string, as determined above, followed by an underscore and then the interaction number within the Response File being processed. This should give a unique naming convention for each .tunerapi call being processed.

Please note that different calls will be handled independently, so for example, if no prefix is defined, and “AudioOutput” is used, this may conflict with the names of audio files generated by different .tunerapi calls – it is therefore important to specify a unique audio_filename_prefix for each individual .tunerapi call.


Include DTMF

The include_dtmf option selects whether DTMF events should be ignored (0) or included (1) in the Export Report File.

Note:

Please note that there is no audio data associated with DTMF events, as LumenVox only processes these events out-of-band.


Include TTS Audio

When the include_tts_audio option is enabled (1), any TTS audio encountered when processing the Response File will be exported and a record will be included in the Export Report File.

If this option is disabled, all TTS interactions will be ignored and no entry will be included in the Export Report File.


Include No-Input Events

When the include_no_input option is enabled, any NO_INPUT type events will be exported, along with any associated audio (if any was recorded). A corresponding entry will be recorded in the Export Report File.

When this option is disabled (0), NO_INPUT events will be ignored and no entry will be included in the Export Report File.


Example .tunerapi File

By way of example, here is a simple .tunerapi configuration file that will export data from the specified input_filename (test1.callsre) and place the output into the specified output_folder (E:\Data\Export API\Output)

[TUNERAPI]
operation = data_export
input_filename = E:\Data\test1.callsre
output_folder = E:\Data\Export API\output
audio_source = decoded
audio_filename_prefix = test
include_dtmf = 0
include_tts_audio = 0
include_no_input = 0

This .tunerapi file, when used with the Speech Tuner will process the specified input_filename and perform the data_export operation, placing output files (audio and Export Report Files) in the E:\Data\Export API\output folder. No DTMF, TTS or NO-INPUT data will be processed. Any audio files generated will use the specified  test prefix and will contain the "decoded" audio source (described above).


Export Report File

An Export Report File will be generated in the target folder and will contain information about interactions that were processed. 

This file will be created if an existing file does not already exist. The first line in this file will be a header, describing the content of the following data.

If an Export Report File does already exist in the target folder, it will be appended to (not overwritten)

The format of this file will include the following values:

Column

Description

timestamp

Timestamp associated with the original interaction (not the API operation)

csp_value

The unique LumenVox internal reference for the interaction

status

Status of the interaction, which can be one of:

  • SRE - a speech recognition event
  • NO_INPUT - a no input event
  • TTS - a TTS synthesis event
  • DTMF - a DTMF event

decode_text

The text result from an ASR or DTMF decode

confidence_score

The confidence score related to the interaction (0-1000 scale)

confidence_threshold

The active confidence threshold for the interaction at that portion of the session (0 if none set)

logging_tag

The corresponding Logging-Tag associated with the interaction (if any)

comments

Comments relating to each interaction processed as it applies to the requested operation.

Table 2 : Report File Fields


Using the Speech Tuner Data Export API

This functionality is designed to be called from a DOS command prompt and can therefore be called manually, by a batch file, or similar process, allowing the automated processing of Response Files as needed.

The only parameter needed to initiate the Data Export API is the .tunerapi configuration file itself, so to call this from the command line; users simply need to specify the name of the configuration file after the SpeechTuner, as shown here:

> SpeechTuner.exe export.tunerapi

This will launch a new instance of the Speech Tuner process, which will review the “export.tunerapi” file and use the configuration values contained within to process the specified Response File and generate the export results in the specified folder, if possible.

After processing of the Data Export API request, the Speech Tuner will then shut down. This will happen whether the request was successful or not, allowing it to be called again within an automated process.


Processing Parallel Data Export API Requests

It is possible to perform multiple Data Export API calls in parallel, if desired. This may be useful if there are many data export requests that are required for example, so using multiple instances will process these requests in parallel, allowing all requests to be processed significantly faster.

Important:

Note that each request starts a unique Speech Tuner instance to perform the task, therefore a Speech Tuner license will be needed for each instance. You can purchase additional Speech Tuner licenses, if needed, from your LumenVox Account Manager.