syntax = "proto3";

package speechkit.tts.v3;

option go_package = "github.com/yandex-cloud/go-genproto/yandex/cloud/ai/tts/v3;tts";
option java_package = "yandex.cloud.api.ai.tts.v3";

message AudioContent {
    // The audio source to read the data from.
    oneof AudioSource {
        // Bytes with audio data.
        bytes content = 1;
    }

    // Description of the audio format.
    AudioFormatOptions audio_spec = 2;
}

message AudioFormatOptions {
    oneof AudioFormat {
        // The audio format specified in request parameters.
        RawAudio raw_audio = 1;

        // The audio format specified inside the container metadata.
        ContainerAudio container_audio = 2;
    }
}

message RawAudio {
    enum AudioEncoding {
        AUDIO_ENCODING_UNSPECIFIED = 0;

        // 16-bit signed little-endian (Linear PCM).
        LINEAR16_PCM = 1;
    }

    // Encoding type.
    AudioEncoding audio_encoding = 1;

    // Sampling frequency of the signal.
    int64 sample_rate_hertz = 2;
}

message ContainerAudio {
    enum ContainerAudioType {
        CONTAINER_AUDIO_TYPE_UNSPECIFIED = 0;

        // RIFF linear pcm with header audio file format.
        WAV = 1;
        OGG_OPUS = 2;
    }
    ContainerAudioType container_audio_type = 1;
}


message TextVariable {
    // The name of the variable.
    string variable_name = 1;
    // The text of the variable.
    string variable_value = 2;
}

message AudioVariable {
    // The name of the variable.
    string variable_name = 1;
    // Start time of the variable in milliseconds.
    int64 variable_start_ms = 2;
    // Lenght of the variable in milliseconds.
    int64 variable_length_ms = 3;
}

message UtteranceSynthesisResponse {
    // Part of synthesized audio.
    AudioChunk audio_chunk = 1;
}

message AudioTemplate {
    // Audio file.
    AudioContent audio = 1;
    // Template and description of its variables.
    TextTemplate text_template = 2;
    // Describing variables in audio.
    repeated AudioVariable variables = 3;
}

message AudioChunk {
    // Sequence of bytes of the synthesized audio in format specified in output_audio_spec.
    bytes data = 1;
}

message TextTemplate {
    // Template text.
    //
    // Sample:`The {animal} goes to the {place}.`
    string text_template = 1;
    // Defining variables in template text.
    //
    // Sample: `{animal: cat, place: forest}`
    repeated TextVariable variables = 2;
}


message Hints {
    // The hint for TTS engine to specify synthesised audio characteristics. 
    oneof Hint {
        // Name of speaker to use.
        string voice = 1;
        // Template for synthesizing.
        AudioTemplate audio_template = 2;
        // hint to change speed
        double speed = 3;
        // hint to regulate volume
        double volume = 4;
    }
}

message UtteranceSynthesisRequest {
    // The name of the model.
    //
    // Currently avalible only `general`.
    string model = 1;
    // Text to synthesis, one of text synthesis markups.
    oneof Utterance {
        // Raw text (e.g. "Hello, Alice").
        string text = 2;
        // Text template instalce, e.g. `{"Hello, {username}" with username="Alice"}`.
        TextTemplate text_template = 3;
    }
    // Optional hints for synthesis.
    repeated Hints hints = 4;
    // Optional. Default: 22050 Hz, linear 16-bit signed little-endian PCM, with WAV header
    AudioFormatOptions output_audio_spec = 5;
}