syntax = "proto2";

package google.internal.communications.voicemailtranscription.v1;

option java_multiple_files = true;

option java_package = "com.google.internal.communications.voicemailtranscription.v1";

// Enum that specifies supported audio formats.
enum AudioFormat {
  // Default but invalid value.
  AUDIO_FORMAT_UNSPECIFIED = 0;

  // Adaptive Multi-Rate Narrowband, 8kHz sampling frequency.
  // https://en.wikipedia.org/wiki/Adaptive_Multi-Rate_audio_codec
  AMR_NB_8KHZ = 1;
}

// Enum that describes the status of the transcription process.
enum TranscriptionStatus {
  // Default but invalid value.
  TRANSCRIPTION_STATUS_UNSPECIFIED = 0;

  // Transcription was successful and the transcript is present.
  SUCCESS = 1;

  // Transcription is progress. Check again later.
  PENDING = 2;

  // Transcription was successful, but the expiration period has passed, which
  // means that the sensative data (including the transcript) has been deleted.
  // Resend the voicemail through TranscribeVoicemailAsync to retry.
  EXPIRED = 3;

  // Internal error encountered during the transcription.
  // Resend the voicemail through TranscribeVoicemailAsync to retry.
  // This is a catch-all status for all retriable errors that aren't captured by
  // a more specfic status.
  FAILED_RETRY = 4;

  // Internal error encountered during the transcription.
  // Do not resend the voicemail.
  // This is a catch-all status for all non-retriable errors that aren't
  // captured by a more specfic status.
  FAILED_NO_RETRY = 5;

  // The language detected is not yet supported by this service.
  // Do not resend the voicemail.
  FAILED_LANGUAGE_NOT_SUPPORTED = 6;

  // No speech was detected in the voicemail.
  // Do not resend the voicemail.
  FAILED_NO_SPEECH_DETECTED = 7;
}

// Enum that specifies the user's consent to donate a specific voicemail.
enum DonationPreference {
  // Default but invalid value.
  USER_PREFERENCE_UNSPECIFIED = 0;

  // User does not consent to donating this voicemail.
  DO_NOT_DONATE = 1;

  // User consents to donating this voicemail.
  DONATE = 2;
}

// Enum that specifies the user's rating for a voicemail transcription.
enum TranscriptionRatingValue {
  // Default but invalid value.
  TRANSCRIPTION_RATING_VALUE_UNSPECIFIED = 0;

  // User indicated that the transcription was good.
  GOOD_TRANSCRIPTION = 1;

  // User indicated that the transcription was bad.
  BAD_TRANSCRIPTION = 2;
}

// Request for synchronous voicemail transcription.
message TranscribeVoicemailRequest {
  // Voicemail audio file containing the raw bytes we receive from the carrier.
  optional bytes voicemail_data = 1;

  // Audio format of the voicemail file.
  optional AudioFormat audio_format = 2;
}

// Response for synchronous voicemail transcription.
message TranscribeVoicemailResponse {
  // The transcribed text of the voicemail.
  optional string transcript = 1;
}

// Request for asynchronous voicemail transcription.
message TranscribeVoicemailAsyncRequest {
  // Voicemail audio data encoded in the format specified by audio_format.
  optional bytes voicemail_data = 1;

  // Audio format of the voicemail file.
  optional AudioFormat audio_format = 2;

  // The client may provide their own unique ID for this transcription. It
  // should be globally unique across all voicemails from all users.
  // If the given transcription_id is not unique, an ALREADY_EXISTS (409) error
  // will be returned.
  // If no transcription_id is provided, one will be generated by the server.
  optional string transcription_id = 3;

  // User's donation preference.
  optional DonationPreference donation_preference = 4;
}

// Response for asynchronous voicemail transcription containing information
// needed to fetch the transcription results through the GetTranscript method.
message TranscribeVoicemailAsyncResponse {
  // Unique ID for the transcription. This ID is used for retrieving the
  // voicemail transcript later.
  optional string transcription_id = 1;

  // The estimated amount of time in seconds before the transcription will be
  // available.
  // The client should not call GetTranscript until this time has elapsed, but
  // the transcript is not guaranteed to be ready by this time.
  optional int64 estimated_wait_secs = 2;
}

// Request for retrieving an asynchronously generated transcript.
message GetTranscriptRequest {
  // Unique ID for the transcription. This ID was returned by
  // TranscribeVoicemailAsync.
  optional string transcription_id = 1;
}

// Response for retrieving an asynchronously generated transcript.
message GetTranscriptResponse {
  // Status of the trascription process.
  optional TranscriptionStatus status = 1;

  // The transcribed text of the voicemail. This is only present if the status
  // is SUCCESS.
  optional string transcript = 2;
}

// The rating for a single voicemail transcription.
message TranscriptionRating {
  // The id of the voicemail transcription.
  optional string transcription_id = 1;

  // The user's rating of the voicemail transcription.
  optional TranscriptionRatingValue rating_value = 2;
}

// Request for uploading transcription ratings.
message SendTranscriptionFeedbackRequest {
  // User feedback indicating the transcription quality for one or more
  // voicemails
  repeated TranscriptionRating rating = 1;
}

// Response for uploading transcription ratings
message SendTranscriptionFeedbackResponse {
}

// RPC service for transcribing voicemails.
service VoicemailTranscriptionService {
  // Returns a transcript of the given voicemail.
  rpc TranscribeVoicemail(TranscribeVoicemailRequest)
      returns (TranscribeVoicemailResponse) {}

  // Schedules a transcription of the given voicemail. The transcript can be
  // retrieved using the returned ID.
  rpc TranscribeVoicemailAsync(TranscribeVoicemailAsyncRequest)
      returns (TranscribeVoicemailAsyncResponse) {
  }

  // Returns the transcript corresponding to the given ID, which was returned
  // by TranscribeVoicemailAsync.
  rpc GetTranscript(GetTranscriptRequest) returns (GetTranscriptResponse) {
  }

  // Uploads user's transcription feedback. Feedback will only be collected from
  // user's who have consented to donate their voicemails.
  rpc SendTranscriptionFeedback(SendTranscriptionFeedbackRequest)
      returns (SendTranscriptionFeedbackResponse) {
  }
}