data.proto

// Copyright 2024 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     https://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

syntax = "proto3";

package google.events.cloud.speech.v1;

import "google/protobuf/timestamp.proto";

option csharp_namespace = "Google.Events.Protobuf.Cloud.Speech.V1";
option php_namespace = "Google\\Events\\Cloud\\Speech\\V1";
option ruby_package = "Google::Events::Cloud::Speech::V1";

// A set of words or phrases that represents a common concept likely to appear
// in your audio, for example a list of passenger ship names. CustomClass items
// can be substituted into placeholders that you set in PhraseSet phrases.
message CustomClass {
  // An item of the class.
  message ClassItem {
    // The class item's value.
    string value = 1;
  }

  // Set of states that define the lifecycle of a CustomClass.
  enum State {
    // Unspecified state.  This is only used/useful for distinguishing
    // unset values.
    STATE_UNSPECIFIED = 0;

    // The normal and active state.
    ACTIVE = 2;

    // This CustomClass has been deleted.
    DELETED = 4;
  }

  // The resource name of the custom class.
  string name = 1;

  // If this custom class is a resource, the custom_class_id is the resource id
  // of the CustomClass. Case sensitive.
  string custom_class_id = 2;

  // A collection of class items.
  repeated ClassItem items = 3;

  // Output only. The [KMS key
  // name](https://cloud.google.com/kms/docs/resource-hierarchy#keys) with which
  // the content of the ClassItem is encrypted. The expected format is
  // `projects/{project}/locations/{location}/keyRings/{key_ring}/cryptoKeys/{crypto_key}`.
  string kms_key_name = 6;

  // Output only. The [KMS key version
  // name](https://cloud.google.com/kms/docs/resource-hierarchy#key_versions)
  // with which content of the ClassItem is encrypted. The expected format is
  // `projects/{project}/locations/{location}/keyRings/{key_ring}/cryptoKeys/{crypto_key}/cryptoKeyVersions/{crypto_key_version}`.
  string kms_key_version_name = 7;

  // Output only. System-assigned unique identifier for the CustomClass.
  // This field is not used.
  string uid = 8;

  // Output only. User-settable, human-readable name for the CustomClass. Must
  // be 63 characters or less. This field is not used.
  string display_name = 9;

  // Output only. The CustomClass lifecycle state.
  // This field is not used.
  State state = 10;

  // Output only. The time at which this resource was requested for deletion.
  // This field is not used.
  google.protobuf.Timestamp delete_time = 11;

  // Output only. The time at which this resource will be purged.
  // This field is not used.
  google.protobuf.Timestamp expire_time = 12;

  // Output only. Allows users to store small amounts of arbitrary data.
  // Both the key and the value must be 63 characters or less each.
  // At most 100 annotations.
  // This field is not used.
  map<string, string> annotations = 13;

  // Output only. This checksum is computed by the server based on the value of
  // other fields. This may be sent on update, undelete, and delete requests to
  // ensure the client has an up-to-date value before proceeding. This field is
  // not used.
  string etag = 14;

  // Output only. Whether or not this CustomClass is in the process of being
  // updated. This field is not used.
  bool reconciling = 15;
}

// Provides "hints" to the speech recognizer to favor specific words and phrases
// in the results.
message PhraseSet {
  // A phrases containing words and phrase "hints" so that
  // the speech recognition is more likely to recognize them. This can be used
  // to improve the accuracy for specific words and phrases, for example, if
  // specific commands are typically spoken by the user. This can also be used
  // to add additional words to the vocabulary of the recognizer. See
  // [usage limits](https://cloud.google.com/speech-to-text/quotas#content).
  //
  // List items can also include pre-built or custom classes containing groups
  // of words that represent common concepts that occur in natural language. For
  // example, rather than providing a phrase hint for every month of the
  // year (e.g. "i was born in january", "i was born in febuary", ...), use the
  // pre-built `$MONTH` class improves the likelihood of correctly transcribing
  // audio that includes months (e.g. "i was born in $month").
  // To refer to pre-built classes, use the class' symbol prepended with `$`
  // e.g. `$MONTH`. To refer to custom classes that were defined inline in the
  // request, set the class's `custom_class_id` to a string unique to all class
  // resources and inline classes. Then use the class' id wrapped in $`{...}`
  // e.g. "${my-months}". To refer to custom classes resources, use the class'
  // id wrapped in `${}` (e.g. `${my-months}`).
  //
  // Speech-to-Text supports three locations: `global`, `us` (US North America),
  // and `eu` (Europe). If you are calling the `speech.googleapis.com`
  // endpoint, use the `global` location. To specify a region, use a
  // [regional endpoint](https://cloud.google.com/speech-to-text/docs/endpoints)
  // with matching `us` or `eu` location value.
  message Phrase {
    // The phrase itself.
    string value = 1;

    // Hint Boost. Overrides the boost set at the phrase set level.
    // Positive value will increase the probability that a specific phrase will
    // be recognized over other similar sounding phrases. The higher the boost,
    // the higher the chance of false positive recognition as well. Negative
    // boost will simply be ignored. Though `boost` can accept a wide range of
    // positive values, most use cases are best served
    // with values between 0 and 20. We recommend using a binary search approach
    // to finding the optimal value for your use case as well as adding
    // phrases both with and without boost to your requests.
    float boost = 2;
  }

  // Set of states that define the lifecycle of a CustomClass.
  enum State {
    // Unspecified state.  This is only used/useful for distinguishing
    // unset values.
    STATE_UNSPECIFIED = 0;

    // The normal and active state.
    ACTIVE = 2;

    // This CustomClass has been deleted.
    DELETED = 4;
  }

  // The resource name of the phrase set.
  string name = 1;

  // A list of word and phrases.
  repeated Phrase phrases = 2;

  // Hint Boost. Positive value will increase the probability that a specific
  // phrase will be recognized over other similar sounding phrases. The higher
  // the boost, the higher the chance of false positive recognition as well.
  // Negative boost values would correspond to anti-biasing. Anti-biasing is not
  // enabled, so negative boost will simply be ignored. Though `boost` can
  // accept a wide range of positive values, most use cases are best served with
  // values between 0 (exclusive) and 20. We recommend using a binary search
  // approach to finding the optimal value for your use case as well as adding
  // phrases both with and without boost to your requests.
  float boost = 4;

  // Output only. The [KMS key
  // name](https://cloud.google.com/kms/docs/resource-hierarchy#keys) with which
  // the content of the PhraseSet is encrypted. The expected format is
  // `projects/{project}/locations/{location}/keyRings/{key_ring}/cryptoKeys/{crypto_key}`.
  string kms_key_name = 7;

  // Output only. The [KMS key version
  // name](https://cloud.google.com/kms/docs/resource-hierarchy#key_versions)
  // with which content of the PhraseSet is encrypted. The expected format is
  // `projects/{project}/locations/{location}/keyRings/{key_ring}/cryptoKeys/{crypto_key}/cryptoKeyVersions/{crypto_key_version}`.
  string kms_key_version_name = 8;

  // Output only. System-assigned unique identifier for the PhraseSet.
  // This field is not used.
  string uid = 9;

  // Output only. User-settable, human-readable name for the PhraseSet. Must be
  // 63 characters or less. This field is not used.
  string display_name = 10;

  // Output only. The CustomClass lifecycle state.
  // This field is not used.
  State state = 11;

  // Output only. The time at which this resource was requested for deletion.
  // This field is not used.
  google.protobuf.Timestamp delete_time = 12;

  // Output only. The time at which this resource will be purged.
  // This field is not used.
  google.protobuf.Timestamp expire_time = 13;

  // Output only. Allows users to store small amounts of arbitrary data.
  // Both the key and the value must be 63 characters or less each.
  // At most 100 annotations.
  // This field is not used.
  map<string, string> annotations = 14;

  // Output only. This checksum is computed by the server based on the value of
  // other fields. This may be sent on update, undelete, and delete requests to
  // ensure the client has an up-to-date value before proceeding. This field is
  // not used.
  string etag = 15;

  // Output only. Whether or not this PhraseSet is in the process of being
  // updated. This field is not used.
  bool reconciling = 16;
}

// The data within all PhraseSet events.
message PhraseSetEventData {
  // Optional. The PhraseSet event payload. Unset for deletion events.
  PhraseSet payload = 1;
}

// The data within all CustomClass events.
message CustomClassEventData {
  // Optional. The CustomClass event payload. Unset for deletion events.
  CustomClass payload = 1;
}