// This file was auto-generated by Fern from our API Definition.

import type * as Vapi from "../index.js";

export interface AssistantSpeechWordProgressTiming {
    /** Number of words spoken so far in this turn. */
    wordsSpoken: number;
    /**
     * Total number of words sent to the TTS provider for this turn.
     *
     * **Important**: this value grows across events within a single turn because
     * Minimax synthesizes audio incrementally as the LLM streams tokens. Treat
     * it as "best known total so far" — it will stabilize once synthesis is
     * complete.
     *
     * A value of `0` is a valid sentinel meaning "not yet known". This can occur
     * on the very first `assistant-speech` event of a turn if audio begins
     * playing before the TTS provider has confirmed word-count data. Clients
     * **must** guard against divide-by-zero when computing a progress fraction:
     *
     * ```ts
     * const pct = totalWords > 0 ? wordsSpoken / totalWords : 0;
     * ```
     */
    totalWords: number;
    /**
     * The text of the latest spoken segment (sentence or clause). Use this
     * for caption display — it corresponds to the chunk just confirmed by
     * the TTS provider, unlike `text` on the parent message which carries
     * the full turn text.
     */
    segment?: string | undefined;
    /**
     * Audio duration in milliseconds for the latest spoken segment. Pair
     * with `segment` to animate karaoke-style word reveals — divide the
     * segment text across this duration for approximate per-word timing.
     */
    segmentDurationMs?: number | undefined;
    /**
     * Per-word timestamps for the latest spoken segment. Available when the
     * TTS provider supports word-level timing (e.g. Minimax with
     * subtitle_type: "word"). Syllables from the provider are aggregated
     * into whole words with start/end times relative to the segment start.
     *
     * Use these for precise karaoke-style highlighting instead of
     * interpolating from segmentDurationMs.
     */
    words?: Vapi.AssistantSpeechWordTimestamp[] | undefined;
}
