Audio management

This section contains audio management proto files.

audio_management_service.proto

AudioManager

This service uploads and downloads audio to the system.

gRPC method definitions

gRPC method definitions
Method Name Request Type Response Type Description
GetUploadUrl GetUploadUrl
Request		 GetUploadUrl
Response		 Gets a temporary URL endpoint for audio upload. The calling application should upload the audio to the provided URL.
GetDownloadUrl GetDownloadUrl
Request		 GetDownloadUrl
Response		 Gets a temporary URL endpoint for audio download. Audio is playable and not encrypted.
GetProcessedAudioDetails GetProcessedAudioDetails
Request		 GetProcessedAudioDetails
Response		 Gets detailed information about a processed audio including both read-only and writable properties.
UpdateProcessedAudioDetails UpdateProcessedAudioDetails
Request		 UpdateProcessedAudioDetails
Response		 Updates one or more processed audio properties.
GetMediaSegmentDetails GetMediaSegmentDetails
Request		 GetMediaSegmentDetails
Response		 Gets detailed information about a media segment including both read-only and writable properties.
UpdateMediaSegmentDetails UpdateMediaSegmentDetails
Request		 UpdateMediaSegmentDetails
Response		 Updates one or more media segment properties.
DeleteMediaSegment DeleteMediaSegment
Request		 DeleteMediaSegment
Response		 Deletes the media segment and all its associated processed audio segments. Returns PERMISSION_DENIED for live media, media used for enrollment, media shared in the datashare, and media marked as legal_hold.

Methods with HTTP bindings

GetUploadUrl

  POST /v1/audios/upload-url  

GetDownloadUrl

  POST /v1/audios/download-url  

GetProcessedAudioDetails

  GET /v1/audios/{gk_processed_audio_id.value}/process  

UpdateProcessedAudioDetails

  PATCH /v1/audios/{gk_processed_audio_id.value}/process  

GetMediaSegmentDetails

  GET /v1/mediasegments/{gk_media_segment_id.value}  

UpdateMediaSegmentDetails

  PATCH /v1/mediasegments/{gk_media_segment_id.value}  

DeleteMediaSegment

  DELETE /v1/mediasegments/{gk_media_segment_id.value}  

audio_management_messages.proto

ALaw

ALaw audio format. G.711 audio formats are set to 8kHz.

AudioFormat

The audio format of the media segment.

AudioFormat
Field Type Description
One of audio_format:  
One of the following audio formats.
   pcm PCM Signed 16-bit little endian PCM
   alaw ALaw G.711 A-law, 8kHz
   ulaw ULaw G.711 Mu-law, 8kHz
   mp3 Mp3 Mp3
   g729 G729 G729/G729A
number_of_channels uint32 Number of channels. i.e. mono audios have one channel, while stereo audios have 2 channels.

DeleteMediaSegmentRequest

Input message that defines parameters for DeleteMediaSegment.

Uses the context field as follows:

  • gk_engagement_id: Mandatory
  • gk_session_id: Mandatory
  • gk_scope_id: Mandatory
  • configset_id: Not used
DeleteMediaSegmentRequest
Field Type Description
context nuance.biosec.v1.Context Mandatory. General request context.
gk_media_segment_id nuance.biosec.v1.UniqueId Mandatory. Unique ID of the media segment.

DeleteMediaSegmentResponse

Output message that defines parameters returned by DeleteMediaSegment.

DeleteMediaSegmentResponse
Field Type Description
status nuance.rpc.Status Mandatory. General operation status.

DeviceprintProcessingAttributes

Contains information about the processed audio. Included in GetProcessedAudioDetailsResponse.

DeviceprintProcessingAttributes
Field Type Description
gross_audio google.protobuf.Duration Optional. Amount of gross audio.
net_audio google.protobuf.Duration Optional. Amount of net audio.
not_speech google.protobuf.Duration Optional. Amount of audio containing everything that is not speech, like noise and silence.
snr_db google.protobuf.FloatValue Optional. The SNR (Signal to noise ratio) value of the audio in dB.
speech_level google.protobuf.FloatValue Optional. A measure related to the estimated power of the speech signal. Lower values mean that the signal level is softer.
saturation_level google.protobuf.FloatValue Optional. The number of saturated audio samples for one minute of speech.
perceptual_speech_quality google.protobuf.FloatValue Optional. Pesq: a number in range 0-5, 0 means noise ony, 5 means perfect quality of speech
packet_loss_rate google.protobuf.FloatValue Optional. Packet loss rate expressed as percentage.
channel_scores repeated nuance.biosec.v1.deviceprint.TelephonyChannelScore Optional. Telephony channel identification scores.

G729

The input message that defines the G729/G729A audio format. By default, the G.729/G.729A audio format is set to 8kHz.

GetDownloadUrlRequest

Input message that defines parameters for GetDownloadUrl.

Uses the context field as follows:

  • gk_engagement_id: Not used
  • gk_session_id: Not used
  • gk_scope_id: Mandatory
  • configset_id: Not used
GetDownloadUrlRequest
Field Type Description
context nuance.biosec.v1.Context Mandatory. General request context.
gk_media_segment_id nuance.biosec.v1.UniqueId Mandatory. Unique ID of the media segment to download.
format AudioFormat Optional. The audio format.
container Container Optional. Specifies the audio file’s type.
channel_selector nuance.biosec.v1.AudioChannelSelector Optional. Specify the channel to download when only one channel of a stereo media is needed. For stereo, left is channel 1 and right is channel 2. When not specified, all channels are downloaded.

GetDownloadUrlResponse

Output message that defines parameters returned by GetDownloadUrl.

GetDownloadUrlResponse
Field Type Description
status nuance.rpc.Status Mandatory. General operation status.
media_download_url string Optional. URL for downloading media.

GetMediaSegmentDetailsRequest

Input message that defines parameters for GetMediaSegmentDetails.

Uses the context field as follows:

  • gk_engagement_id: Not used
  • gk_session_id: Not used
  • gk_scope_id: Mandatory
  • configset_id: Not used
GetMediaSegmentDetailsRequest
Field Type Description
context nuance.biosec.v1.Context Mandatory. General request context.
gk_media_segment_id nuance.biosec.v1.UniqueId Mandatory. Unique ID of the media segment.
field_mask google.protobuf.FieldMask Optional. A field mask used to specify the MediaSegmentDetailsForRead fields that the method reads.

GetMediaSegmentDetailsResponse

Output message that defines parameters returned by GetMediaSegmentDetails.

GetMediaSegmentDetailsResponse
Field Type Description
status nuance.rpc.Status Mandatory. General operation status.
details MediaSegmentDetailsForRead Optional. Media segment’s details.

GetProcessedAudioDetailsRequest

Input message that defines parameters for GetProcessedAudioDetails.

Uses the context field as follows:

  • gk_engagement_id: Not used
  • gk_session_id: Not used
  • gk_scope_id: Mandatory
  • configset_id: Not used
GetProcessedAudioDetailsRequest
Field Type Description
context nuance.biosec.v1.Context Mandatory. General request context.
gk_processed_audio_id nuance.biosec.v1.UniqueId Mandatory. Unique ID of the processed audio.
field_mask google.protobuf.FieldMask Optional. A field mask used to specify the ProcessedAudioDetailsForRead fields that the method reads.

GetProcessedAudioDetailsResponse

Output message that defines parameters returned by GetProcessedAudioDetails.

GetProcessedAudioDetailsResponse
Field Type Description
status nuance.rpc.Status Mandatory. General operation status.
details ProcessedAudioDetailsForRead Optional. Audio details.
gk_media_segment_id nuance.biosec.v1.UniqueId Optional. ID of the media segment that is used to generate gk_processed_audio_id.

GetUploadUrlRequest

Input message that defines parameters for GetUploadUrl.

Uses the context field as follows:

  • gk_engagement_id: Mandatory
  • gk_session_id: Mandatory
  • gk_scope_id: Mandatory
  • configset_id: Not used
GetUploadUrlRequest
Field Type Description
context nuance.biosec.v1.Context Mandatory. General request context.
format AudioFormat Optional if uploading a wav file. Mandatory when uploading a header-less audio file.
container Container Mandatory. Specifies the audio file’s type.
call_parties repeated PartyAttributes Optional. Call parties attributes.

GetUploadUrlResponse

Output message that defines parameters returned by GetUploadUrl.

GetUploadUrlResponse
Field Type Description
status nuance.rpc.Status Mandatory. General operation status.
media_upload_url string Optional. URL for uploading media.
gk_media_segment_id nuance.biosec.v1.UniqueId Optional. Uploaded media’s unique Media Segment ID for use in other API methods.

Interval

Contains parameters that define an interval.

Interval
Field Type Description
start_offset google.protobuf.Duration Mandatory. Marks the beginning of the media interval.
end_offset google.protobuf.Duration Optional. Marks the end of the media interval. When not set, the interval stops at the end of media segment and must be the last interval in the list.
channel uint32 Mandatory. Specifies the interval’s media channel.

MediaSegmentDetailsForRead

Contains the readable fields of the media segment. Included in GetMediaSegmentDetailsResponse. Only the fields that match the GetMediaSegmentDetailsRequest are returned. If no mask is specified, all fields are returned.

MediaSegmentDetailsForRead
Field Type Description
gk_person_id nuance.biosec.v1.UniqueId Optional. The unique ID of the person owning the media segment.
legal_hold google.protobuf.BoolValue Optional. Determined if the media should be kept due to a regulatory requirement.
media_length google.protobuf.Duration Optional. Amount of gross audio collected. This represents the actual recording duration excluding the time the call was on hold.
sample_rate_hz google.protobuf.Int32Value Optional. Number of audio samples per second.
number_of_channels google.protobuf.Int32Value Optional. Number of recording channels (1 for Mono, 2 for Stereo).
call_parties repeated PartyAttributes Optional. Parties attributes.
call_type nuance.biosec.v1.CallType Optional. The type of the call.
redacted_intervals repeated Interval Optional. List of redacted intervals for all channels.
masked_intervals repeated Interval Optional. List of masked intervals for all channels.
custom_data repeated MediaSegmentDetailsForRead.CustomDataEntry Optional. Custom application data in a list of key-value pairs.

MediaSegmentDetailsForRead.CustomDataEntry

MediaSegmentDetailsForRead.CustomDataEntry
Field Type Description
key string  
value string  

MediaSegmentDetailsForWrite

Contains the writable fields of the media segment. Included in UpdateMediaSegmentDetailsRequest. Provide fields that match UpdateMediaSegmentDetailsRequest.

MediaSegmentDetailsForWrite
Field Type Description
gk_person_id nuance.biosec.v1.UniqueId Optional. The unique ID of the person owning the media segment.
legal_hold google.protobuf.BoolValue Optional. Determined if the media should be kept due to a regulatory requirement.
custom_data repeated MediaSegmentDetailsForWrite.CustomDataEntry Optional. Custom application data in a list of key-value pairs.

MediaSegmentDetailsForWrite.CustomDataEntry

MediaSegmentDetailsForWrite.CustomDataEntry
Field Type Description
key string  
value string  

Mp3

MP3 audio format

Mp3
Field Type Description
target Target Optimize for quality or bitrate.
bitrate uint32 Bitrate in kbit/sec (Only valid if target is bitrate, for CBR one of 8, 16, 24, 32, 40, 48, 56, 64, 80, 96, 112, 128, 160, 192, 224, 256 or 320)
cbr bool Enforces constant bitrate encoding (Only valid if target is bitrate)
quality float VBR Quality from 0 to 10, 0 being the best (Only valid if target is quality)
mono bool Enforces mono encoding
encoding_engine_quality EncodingEngineQuality Quality/speed of the encoding engine, this does not affect the bitrate!

PCM

PCM audio format

PCM
Field Type Description
sample_rate_hz uint32 Audio sample rate. Default 0, meaning 8000.

PartyAttributes

Attributes of a call party.

PartyAttributes
Field Type Description
channel_index int32 Optional. The channel index. Valid values are between 1 and the number of channels.
party_type PartyType Optional. The party type.
gk_party_id nuance.biosec.v1.UniqueId Optional. The ID associated with this party.

ProcessedAudioDetailsForRead

Contains the readable fields of the Processed Audio. Included in GetProcessedAudioDetailsResponse. Only fields that match the GetProcessedAudioDetailsRequest are returned. If no mask is specified, all fields are returned.

ProcessedAudioDetailsForRead
Field Type Description
gk_calibration_model_revision_id nuance.biosec.v1.UniqueId Optional. Unique ID of the calibration model that the system used to create the audio model.
gk_playback_calibration_model_revision_id nuance.biosec.v1.UniqueId Optional. Unique ID of the calibration model that the system used to perform channel playback detection.
processed_audio_attributes RecordingAttributes Optional. Processed audio recording details.
One of attributes:  
Optional, there is only one of them, according to processing type.
   processing_attributes ProcessingAttributes Optional. Audio processing details.
   deviceprint_processing_attributes DeviceprintProcessingAttributes Optional. Audio processing details specific for deviceprint operations.
voice_class_score google.protobuf.FloatValue Optional. A score between 0 and 100 that can be used to categorize voices into classes according to various factors such as timbre, pitch, and so on.
actual_language string Optional. The language spoken in the audio. This info is provided by the client.
creation_timestamp google.protobuf.Timestamp Optional. Date and time of the processed audio segment creation.
modification_timestamp google.protobuf.Timestamp Optional. Date and time of last modification.
custom_data repeated ProcessedAudioDetailsForRead.CustomDataEntry Optional. Custom application data in a list of key-value pairs.

ProcessedAudioDetailsForRead.CustomDataEntry

ProcessedAudioDetailsForRead.CustomDataEntry
Field Type Description
key string  
value string  

ProcessedAudioDetailsForWrite

Contains the writable fields of the processed audio segment. Included in UpdateProcessedAudioDetailsRequest. Provide fields that match UpdateProcessedAudioDetailsRequest.

ProcessedAudioDetailsForWrite
Field Type Description
actual_language string The language spoken in the audio. This info is provided by the client.
custom_data repeated ProcessedAudioDetailsForWrite.CustomDataEntry Custom application data in a list of key-value pairs.

ProcessedAudioDetailsForWrite.CustomDataEntry

ProcessedAudioDetailsForWrite.CustomDataEntry
Field Type Description
key string  
value string  

ProcessingAttributes

Contains information about the processed audio. Included in GetProcessedAudioDetailsResponse.

ProcessingAttributes
Field Type Description
gross_audio google.protobuf.Duration Optional. Amount of gross audio.
net_audio google.protobuf.Duration Optional. Amount of net audio.
snr_db google.protobuf.FloatValue Optional. The SNR (Signal to noise ratio) value of the audio in dB.
speech_level google.protobuf.FloatValue Optional. A measure related to the estimated power of the speech signal. Lower values mean that the signal level is softer.
saturation_level google.protobuf.FloatValue Optional. The number of saturated audio samples for one minute of speech.
synthetic_score google.protobuf.FloatValue Optional. Synthetic Speech Detection score.
channel_playback_score google.protobuf.FloatValue Optional. Channel Playback Detection score.
playback_version google.protobuf.Int32Value Optional. Version of the playback algorithm used to compute the score.

RecordingAttributes

Contains information about the processed audio recording. Included in GetProcessedAudioDetailsResponse.

RecordingAttributes
Field Type Description
sample_rate_hz google.protobuf.Int32Value Optional. Number of audio samples per second.
number_of_channels google.protobuf.Int32Value Optional. Number of recording channels (1 for Mono, 2 for Stereo).
selected_channel nuance.biosec.v1.AudioChannelSelector Optional. Specifies the processed channel when processing media with multiple channels. This parameter is not set if the media has a single channel.

ULaw

ULaw audio format. G.711 audio formats are set to 8kHz.

UpdateMediaSegmentDetailsRequest

Input message that defines parameters for UpdateMediaSegmentDetails.

Uses the context field as follows:

  • gk_engagement_id: Mandatory
  • gk_session_id: Mandatory
  • gk_scope_id: Mandatory
  • configset_id: Not used
UpdateMediaSegmentDetailsRequest
Field Type Description
context nuance.biosec.v1.Context Mandatory. General request context.
gk_media_segment_id nuance.biosec.v1.UniqueId Mandatory. Unique ID of the media segment.
details MediaSegmentDetailsForWrite Mandatory. Fields that the method sets or updates.
field_mask google.protobuf.FieldMask Mandatory. A field mask used to specify the MediaSegmentDetailsForWrite fields to set.

UpdateMediaSegmentDetailsResponse

Output message that defines parameters returned by UpdateMediaSegmentDetails.

UpdateMediaSegmentDetailsResponse
Field Type Description
status nuance.rpc.Status Mandatory. General operation status.

UpdateProcessedAudioDetailsRequest

Input message that defines parameters for UpdateProcessedAudioDetails.

Uses the context field as follows:

  • gk_engagement_id: Mandatory
  • gk_session_id: Mandatory
  • gk_scope_id: Mandatory
  • configset_id: Not used
UpdateProcessedAudioDetailsRequest
Field Type Description
context nuance.biosec.v1.Context Mandatory. General request context.
gk_processed_audio_id nuance.biosec.v1.UniqueId Mandatory. Unique ID of the processed audio.
details ProcessedAudioDetailsForWrite Mandatory. Fields that the method sets or updates.
field_mask google.protobuf.FieldMask Mandatory. A field mask used to specify the ProcessedAudioDetailsForWrite fields to set.

UpdateProcessedAudioDetailsResponse

Output message that defines parameters returned by UpdateProcessedAudioDetails.

UpdateProcessedAudioDetailsResponse
Field Type Description
status nuance.rpc.Status Mandatory. General operation status.

Container

The audio file type.

Name Number Description
CONTAINER_UNSPECIFIED 0 The audio file type is not specified.
CONTAINER_RAW 1 The audio file type is raw.
CONTAINER_WAV 2 The audio file type is wav.
CONTAINER_MP3 3 The audio file type is mp3.

EncodingEngineQuality

Encoding engine quality

Name Number Description
ENCODING_ENGINE_QUALITY_UNSPECIFIED 0 Encoding quality engine is not specified.
ENCODING_ENGINE_QUALITY_FAST 1 Encoding quality engine is ‘Fast’.
ENCODING_ENGINE_QUALITY_STANDARD 2 Encoding quality engine is ‘Standard’.
ENCODING_ENGINE_QUALITY_HIGH 3 Encoding quality engine is ‘High’.

PartyType

The party type.

Name Number Description
PARTY_TYPE_UNSPECIFIED 0 Party type is not set.
PARTY_TYPE_AGENT 1 Party type is agent.
PARTY_TYPE_PERSON 2 Party type is person.
PARTY_TYPE_IVR 3 Party type is IVR.
PARTY_TYPE_OTHER 999 Party type is other.

Target

Name Number Description
TARGET_UNSPECIFIED 0 Target is not specified.
TARGET_QUALITY 1 Target is quality.
TARGET_BITRATE 2 Target is bitrate.