We enabled use_tts_aligned_transcript=True and are using a TTS that supports aligned transcript (Cartesia with word_timestamps). The client still receives start_time=0, end_time=0 on every transcription segment from useTrackTranscription.

We traced this to livekit/agents/voice/room_io/_output.py: _ParticipantLegacyTranscriptionOutput._publish_transcription always passes start_time=0, end_time=0 into TranscriptionSegment and never uses the TimedString start/end times from the pipeline. So even when the pipeline produces timed text, the legacy transcription path doesn’t publish it.

Question: Is the intent that real timecodes be published when use_tts_aligned_transcript=True and the TTS provides aligned transcript? If yes, will the SDK be updated so that _publish_transcription (and/or the stream path) uses the pipeline’s TimedString times instead of 0,0? Or is there another supported way to get real segment timecodes to the client without patching the SDK?

useTrackTranscription

use_tts_aligned_transcript=True

word_timestamps

use_tts_aligned_transcript=True

lk.transcription

_ParticipantLegacyTranscriptionOutput._publish_transcription

start_time=0

end_time=0

TimedString

TimedString

transcription_node

TimedString

start_time

end_time

use_tts_aligned_transcript=True

TranscriptionSegment

TimedString

lk.transcription

transcription_node

TimedString

transcription_node

TimedString

my_transcription_stream

TimedString

Thanks for confirming. We’d like the Python snippet for the transcription_node approach that publishes TimedString (text, start_time, end_time) to a custom topic, plus the client-side handler to consume it. We’re on the LiveKit Agents Python SDK (agents run in Python); frontend is

transcription_node

TimedString

TimedString

text

start_time

end_time

my_transcription_stream

import json
from typing import AsyncIterable
from livekit import TimedString  # adjust import if TimedString path differs

# Example transcription_node signature used by the Agents Python SDK
async def transcription_node(
    self,
    text: AsyncIterable[str | TimedString],
    model_settings,  # keep signature compatible with your pipeline
) -> AsyncIterable[str | TimedString]:
    """
    For each TimedString from the pipeline, publish a JSON message to a custom
    text stream topic 'my_transcription_stream'. Yield objects onward so the
    rest of the pipeline still works.
    """
    async for chunk in text:
        # If the pipeline yields TimedString, it should have .text, .start_time, .end_time
        if isinstance(chunk, TimedString):
            payload = {
                "type": "timed_transcription",
                "text": chunk.text,
                "start_time": chunk.start_time,  # seconds (float)
                "end_time": chunk.end_time,      # seconds (float)
                # optional: include sequence, confidence, word-level list, etc.
            }
            # publish as a text stream on a custom topic
            try:
                # session.room.local_participant is typically available in Agents code
                await self.session.room.local_participant.publish_data(
                    json.dumps(payload),
                    topic="my_transcription_stream",
                )
            except Exception as e:
                # Log and continue; do not block the pipeline on publish errors
                self.logger.exception("failed to publish timed transcription: %s", e)

            # also yield the TimedString onward (so other nodes still receive it)
            yield chunk
        else:
            # plain string chunk
            yield chunk

self.session.room.local_participant.publish_data

payload

word_timestamps

Room

livekit-client

@livekit/components-react

useRoom

my_transcription_stream

import { useEffect } from "react";
import { Room, DataPacket_Kind } from "livekit-client";
import { useRoom } from "@livekit/components-react";

type TimedTranscriptionPayload = {
  type: "timed_transcription";
  text: string;
  start_time: number; // seconds
  end_time: number;   // seconds
  // optional: word-level array, sequence id, etc.
};

export function useTimedTranscription(handler: (msg: TimedTranscriptionPayload) => void) {
  const { room } = useRoom(); // or obtain Room instance another way

  useEffect(() => {
    if (!room) return;

    // reader-based API: registerTextStreamHandler / registerDataReceiver
    // Some SDK versions expose registerTextStreamHandler(topic, handler)
    const topic = "my_transcription_stream";

    const textHandler = async (reader: ReadableStreamDefaultReader<Uint8Array>) => {
      // readAll convenience if available, else iterate
      try {
        // If the SDK provides `readAll()`:
        // const raw = await reader.readAll();
        // const ok = raw && raw.length > 0;
        // For portability, we'll loop:
        while (true) {
          const { value, done } = await reader.read();
          if (done) break;
          const str = new TextDecoder().decode(value);
          try {
            const payload = JSON.parse(str) as TimedTranscriptionPayload;
            handler(payload);
          } catch (e) {
            console.error("failed to parse timed transcription", e, str);
          }
        }
      } catch (err) {
        console.error("text stream handler error", err);
      }
    };

    // Register the handler. API name may vary by client version:
    // - room.registerTextStreamHandler(topic, textHandler)
    // - room.on("dataReceived", ...) OR room.registerDataReceiver
    // Try registerTextStreamHandler first:
    let unregister: (() => void) | undefined;

    if ((room as any).registerTextStreamHandler) {
      (room as any).registerTextStreamHandler(topic, textHandler);
      unregister = () => {
        try {
          (room as any).unregisterTextStreamHandler(topic);
        } catch {}
      };
    } else if ((room as any).onDataReceived) {
      // Fallback: listen for data messages and filter by topic
      const onData = (payload: Uint8Array, kind: DataPacket_Kind, participant?: any, topics?: string[]) => {
        // Only process if topic matches (topics param depends on SDK)
        if (topics && topics.includes(topic)) {
          const str = new TextDecoder().decode(payload);
          try {
            const parsed = JSON.parse(str) as TimedTranscriptionPayload;
            handler(parsed);
          } catch (e) {
            console.error("failed to parse timed transcription", e, str);
          }
        }
      };
      room.on("dataReceived", onData);
      unregister = () => room.off("dataReceived", onData);
    } else {
      console.warn("room.registerTextStreamHandler not available in this SDK version");
    }

    return () => {
      if (unregister) unregister();
    };
  }, [room, handler]);
}

start_time

end_time

// pseudo-usage inside a React component
useTimedTranscription((payload) => {
  // Store into local state or enqueue for timed reveal
  enqueueCaption({
    text: payload.text,
    start: Date.now() + payload.start_time * 1000, // if mapping to absolute time
    end: Date.now() + payload.end_time * 1000,
  });
});

transcription_node

my_transcription_stream

lk.transcription

livekit/agents/voice/room_io/_output.py

_ParticipantLegacyTranscriptionOutput._publish_transcription

start_time=0

end_time=0

TranscriptionSegment

TimedString

lk.transcription

use_tts_aligned_transcript=True

TimedString

lk.transcription

_publish_transcription

TimedString.start_time

TimedString.end_time

useTrackTranscription(agentTrack)

transcription_node

transcription_node

_publish_transcription

TimedString

TranscriptionSegment