fix: useTranscription now handles data channel events (#13) (#22)

Fix `useTranscription` never firing because the backend sends transcript data over `RoomEvent.DataReceived` (data channel) rather than `RoomEvent.TranscriptionReceived`.

Closes #13

### What changed

- Extract shared data-channel parsing into `src/utils/parseTranscription.ts` (with 18 tests)
- Wire `useTranscription` to listen on `DataReceived` alongside `TranscriptionReceived`
- Refactor `useTranscript` to import from the shared module (no behavior change)

### Verify

Both `useTranscription` (callback) and `useTranscript` (accumulated state) should receive transcript entries during a live avatar session.

Author: robinandeer

CHANGELOG.md

@@ -13,7 +13,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
-- `useTranscript` merges data-channel transcript JSON from `RoomEvent.DataReceived` when `{ mergeDataChannelSegments: true }` (default): LiveKit-style `{ segments: [...] }` and Runway worker `{ type: "transcription", role, turn, text }` streaming deltas (concatenated per role+turn). Set `{ mergeDataChannelSegments: false }` to use only `RoomEvent.TranscriptionReceived`.
+- `useTranscription` and `useTranscript` now receive transcription data from all supported transports ([#13](https://github.com/runwayml/avatars-sdk-react/issues/13))
 
 ## [0.12.0] - 2026-04-02
 

src/hooks/useTranscript.ts

@@ -5,6 +5,11 @@ import type { Participant, TranscriptionSegment } from 'livekit-client';
 import { RoomEvent } from 'livekit-client';
 import { useEffect, useRef, useState } from 'react';
 import type { TranscriptionEntry } from '../types';
+import {
+  tryDecodeJSON,
+  tryParseFlatDelta,
+  tryParseSegmentArray,
+} from '../utils/parseTranscription';
 
 export interface UseTranscriptOptions {
   /** Include interim (non-final) segments. Default: `false` */
@@ -22,86 +27,6 @@ export interface UseTranscriptOptions {
 
 const DEFAULT_BUFFER_SIZE = 100;
 
-type DataChannelJSON = Record<string, unknown>;
-
-function tryDecodeJSON(payload: Uint8Array): DataChannelJSON | null {
-  try {
-    const text = new TextDecoder().decode(payload).trim();
-    if (!text.startsWith('{')) return null;
-    const parsed: unknown = JSON.parse(text);
-    return parsed && typeof parsed === 'object'
-      ? (parsed as DataChannelJSON)
-      : null;
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Parse LiveKit-style segment arrays: `{ segments: [{ id, text, final? }] }`
- * Also handles wrapper shapes like `{ type: "transcription", segments: [...] }`
- * and `{ data: { segments: [...] } }`.
- */
-function tryParseSegmentArray(
-  root: DataChannelJSON,
-  participant?: Participant,
-): Array<TranscriptionEntry> | null {
-  const type = root.type;
-  const typeAllowed =
-    type === undefined ||
-    type === 'transcription' ||
-    type === 'transcript' ||
-    type === 'voice_transcript';
-  if (!typeAllowed) return null;
-
-  let segments: unknown = root.segments;
-  if (
-    !Array.isArray(segments) &&
-    root.data &&
-    typeof root.data === 'object'
-  ) {
-    segments = (root.data as DataChannelJSON).segments;
-  }
-  if (!Array.isArray(segments)) return null;
-
-  const identity = participant?.identity ?? 'unknown';
-  const out: Array<TranscriptionEntry> = [];
-
-  for (const item of segments) {
-    if (!item || typeof item !== 'object') continue;
-    const seg = item as DataChannelJSON;
-    if (typeof seg.id !== 'string' || typeof seg.text !== 'string') continue;
-    out.push({
-      id: seg.id,
-      text: seg.text,
-      final: typeof seg.final === 'boolean' ? seg.final : true,
-      participantIdentity:
-        typeof seg.participantIdentity === 'string'
-          ? seg.participantIdentity
-          : identity,
-    });
-  }
-
-  return out.length > 0 ? out : null;
-}
-
-/**
- * Parse Runway flat streaming deltas: `{ type: "transcription", role, turn, text }`
- * These arrive one delta at a time and are accumulated per role+turn.
- */
-function tryParseFlatDelta(
-  root: DataChannelJSON,
-): { role: string; turn: number; textDelta: string } | null {
-  if (root.type !== 'transcription') return null;
-  if (typeof root.text !== 'string') return null;
-
-  return {
-    role: typeof root.role === 'string' ? root.role : 'assistant',
-    turn: typeof root.turn === 'number' ? root.turn : 0,
-    textDelta: root.text,
-  };
-}
-
 /**
  * Hook that returns an accumulated, deduplicated transcript from the session.
  *

src/hooks/useTranscription.ts

@@ -5,6 +5,11 @@ import type { Participant, TranscriptionSegment } from 'livekit-client';
 import { RoomEvent } from 'livekit-client';
 import { useEffect, useRef } from 'react';
 import type { TranscriptionHandler } from '../types';
+import {
+  tryDecodeJSON,
+  tryParseFlatDelta,
+  tryParseSegmentArray,
+} from '../utils/parseTranscription';
 
 /**
  * Hook to listen for transcription events from the session.
@@ -13,7 +18,11 @@ import type { TranscriptionHandler } from '../types';
  * only final segments are delivered. Pass `{ interim: true }` to also
  * receive partial/streaming segments.
  *
- * Must be used within an AvatarSession or AvatarCall component.
+ * Listens to both native `RoomEvent.TranscriptionReceived` and data-channel
+ * JSON (`RoomEvent.DataReceived`) so transcripts work regardless of which
+ * transport the backend uses.
+ *
+ * Must be used within an AvatarSession, AvatarProvider, or AvatarCall component.
  *
  * @example
  * ```tsx
@@ -37,7 +46,11 @@ export function useTranscription(
   const interimRef = useRef(options?.interim ?? false);
   interimRef.current = options?.interim ?? false;
 
+  const flatAccRef = useRef(new Map<string, string>());
+
   useEffect(() => {
+    flatAccRef.current.clear();
+
     function handleTranscription(
       segments: Array<TranscriptionSegment>,
       participant?: Participant,
@@ -54,9 +67,43 @@ export function useTranscription(
       }
     }
 
+    function handleDataReceived(
+      payload: Uint8Array,
+      participant?: Participant,
+    ) {
+      const json = tryDecodeJSON(payload);
+      if (!json) return;
+
+      const segments = tryParseSegmentArray(json, participant);
+      if (segments) {
+        for (const entry of segments) {
+          if (!interimRef.current && !entry.final) continue;
+          handlerRef.current(entry);
+        }
+        return;
+      }
+
+      const delta = tryParseFlatDelta(json);
+      if (delta) {
+        const identity = participant?.identity ?? 'unknown';
+        const accKey = `runway-transcription-${delta.role}-${delta.turn}`;
+        const prev = flatAccRef.current.get(accKey) ?? '';
+        const nextText = prev + delta.textDelta;
+        flatAccRef.current.set(accKey, nextText);
+        handlerRef.current({
+          id: accKey,
+          text: nextText,
+          final: false,
+          participantIdentity: identity,
+        });
+      }
+    }
+
     room.on(RoomEvent.TranscriptionReceived, handleTranscription);
+    room.on(RoomEvent.DataReceived, handleDataReceived);
     return () => {
       room.off(RoomEvent.TranscriptionReceived, handleTranscription);
+      room.off(RoomEvent.DataReceived, handleDataReceived);
     };
   }, [room]);
 }

src/utils/parseTranscription.test.ts

@@ -0,0 +1,158 @@
+import { describe, expect, it } from 'bun:test';
+import {
+  tryDecodeJSON,
+  tryParseFlatDelta,
+  tryParseSegmentArray,
+} from './parseTranscription';
+
+const encode = (obj: unknown) =>
+  new TextEncoder().encode(JSON.stringify(obj));
+
+describe('tryDecodeJSON', () => {
+  it('decodes a valid JSON object payload', () => {
+    const result = tryDecodeJSON(encode({ type: 'transcription', text: 'hi' }));
+    expect(result).toEqual({ type: 'transcription', text: 'hi' });
+  });
+
+  it('returns null for non-JSON payloads', () => {
+    expect(tryDecodeJSON(new Uint8Array([0xff, 0xfe]))).toBeNull();
+  });
+
+  it('returns null for JSON arrays', () => {
+    expect(tryDecodeJSON(new TextEncoder().encode('[1,2,3]'))).toBeNull();
+  });
+
+  it('returns null for empty input', () => {
+    expect(tryDecodeJSON(new Uint8Array([]))).toBeNull();
+  });
+});
+
+describe('tryParseFlatDelta', () => {
+  it('parses a Runway flat transcription delta', () => {
+    const result = tryParseFlatDelta({
+      type: 'transcription',
+      role: 'assistant',
+      turn: 0,
+      text: ' hello',
+    });
+    expect(result).toEqual({ role: 'assistant', turn: 0, textDelta: ' hello' });
+  });
+
+  it('parses user role deltas', () => {
+    const result = tryParseFlatDelta({
+      type: 'transcription',
+      role: 'user',
+      turn: 1,
+      text: 'How are you?',
+    });
+    expect(result).toEqual({
+      role: 'user',
+      turn: 1,
+      textDelta: 'How are you?',
+    });
+  });
+
+  it('defaults role to assistant and turn to 0 when missing', () => {
+    const result = tryParseFlatDelta({ type: 'transcription', text: 'hi' });
+    expect(result).toEqual({ role: 'assistant', turn: 0, textDelta: 'hi' });
+  });
+
+  it('returns null when type is not transcription', () => {
+    expect(
+      tryParseFlatDelta({ type: 'client_event', text: 'hi' }),
+    ).toBeNull();
+  });
+
+  it('returns null when text is missing', () => {
+    expect(
+      tryParseFlatDelta({ type: 'transcription', role: 'assistant', turn: 0 }),
+    ).toBeNull();
+  });
+});
+
+describe('tryParseSegmentArray', () => {
+  it('parses a segments array with explicit type', () => {
+    const result = tryParseSegmentArray({
+      type: 'transcription',
+      segments: [{ id: 'seg-1', text: 'Hello world', final: true }],
+    });
+    expect(result).toEqual([
+      {
+        id: 'seg-1',
+        text: 'Hello world',
+        final: true,
+        participantIdentity: 'unknown',
+      },
+    ]);
+  });
+
+  it('parses segments without a type field', () => {
+    const result = tryParseSegmentArray({
+      segments: [{ id: 'seg-2', text: 'test' }],
+    });
+    expect(result).toHaveLength(1);
+    expect(result?.[0].id).toBe('seg-2');
+    expect(result?.[0].final).toBe(true);
+  });
+
+  it('uses participant identity when provided', () => {
+    const participant = { identity: 'agent-123' } as { identity: string };
+    const result = tryParseSegmentArray(
+      { segments: [{ id: 'seg-3', text: 'hi' }] },
+      participant,
+    );
+    expect(result?.[0].participantIdentity).toBe('agent-123');
+  });
+
+  it('respects participantIdentity on individual segments', () => {
+    const result = tryParseSegmentArray({
+      segments: [
+        { id: 'seg-4', text: 'yo', participantIdentity: 'user-456' },
+      ],
+    });
+    expect(result?.[0].participantIdentity).toBe('user-456');
+  });
+
+  it('handles nested data.segments shape', () => {
+    const result = tryParseSegmentArray({
+      type: 'transcript',
+      data: { segments: [{ id: 'seg-5', text: 'nested' }] },
+    });
+    expect(result).toHaveLength(1);
+    expect(result?.[0].text).toBe('nested');
+  });
+
+  it('returns null for non-transcript type', () => {
+    expect(
+      tryParseSegmentArray({
+        type: 'client_event',
+        segments: [{ id: 's', text: 't' }],
+      }),
+    ).toBeNull();
+  });
+
+  it('returns null when no segments array exists', () => {
+    expect(
+      tryParseSegmentArray({ type: 'transcription', text: 'flat delta' }),
+    ).toBeNull();
+  });
+
+  it('skips malformed segment items', () => {
+    const result = tryParseSegmentArray({
+      segments: [
+        { id: 'good', text: 'valid' },
+        { noId: true, text: 'bad' },
+        null,
+        'string',
+      ],
+    });
+    expect(result).toHaveLength(1);
+    expect(result?.[0].id).toBe('good');
+  });
+
+  it('returns null when all segments are malformed', () => {
+    expect(
+      tryParseSegmentArray({ segments: [{ noId: true }] }),
+    ).toBeNull();
+  });
+});