@vocalstack/js-sdk 1.1.0 → 2.0.0-alpha.1

package/dist/http.d.ts

@@ -0,0 +1,43 @@
+export type Query = Record<string, string | number | boolean | undefined | null>;
+export interface ClientOptions {
+    baseUrl?: string;
+    apiKey?: string;
+    token?: string | (() => string | undefined | null | Promise<string | undefined | null>);
+    actingPrincipal?: string;
+    deviceId?: string;
+    fetch?: typeof fetch;
+    maxRetries?: number;
+    readyDeadlineMs?: number;
+}
+export interface CallOptions {
+    idempotencyKey?: string;
+    signal?: AbortSignal;
+}
+export interface ReadAs {
+    listenerToken?: string;
+    shareCode?: string;
+}
+export declare function listenerQuery(as: ReadAs | undefined): Query;
+export interface RequestInit2 extends CallOptions {
+    query?: Query;
+    body?: unknown;
+    headers?: Record<string, string>;
+    anonymous?: boolean;
+    noRetry?: boolean;
+    oauthErrors?: boolean;
+}
+export declare const DEFAULT_BASE_URL = "https://api.vocalstack.com";
+export declare function qs(q: Query | undefined): string;
+export declare const seg: (s: string | number) => string;
+export declare function retries(status: number, code: string, method: string, idempotencyKey?: string): boolean;
+export declare class Transport {
+    #private;
+    readonly baseUrl: string;
+    readonly opts: ClientOptions;
+    constructor(opts: ClientOptions);
+    bearer(): Promise<string | undefined>;
+    url(path: string, query?: Query): string;
+    wsUrl(path: string, query?: Query): string;
+    raw(method: string, path: string, init?: RequestInit2): Promise<Response>;
+    json<T>(method: string, path: string, init?: RequestInit2): Promise<T>;
+}

package/dist/http.js

@@ -0,0 +1,124 @@
+import { VocalStackError, fromEnvelope, fromOAuth } from './errors.js';
+export function listenerQuery(as) {
+    return { listenerToken: as?.listenerToken, shareCode: as?.shareCode };
+}
+export const DEFAULT_BASE_URL = 'https://api.vocalstack.com';
+export function qs(q) {
+    if (!q)
+        return '';
+    const parts = [];
+    for (const [k, v] of Object.entries(q)) {
+        if (v === undefined || v === null || v === '')
+            continue;
+        parts.push(`${encodeURIComponent(k)}=${encodeURIComponent(String(v))}`);
+    }
+    return parts.length ? `?${parts.join('&')}` : '';
+}
+export const seg = (s) => encodeURIComponent(String(s));
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+const UNAVAILABLE_WAIT_S = 2;
+export function retries(status, code, method, idempotencyKey) {
+    if (status === 429)
+        return true;
+    if (status !== 503 || code !== 'unavailable')
+        return false;
+    const m = method.toUpperCase();
+    return m === 'GET' || m === 'HEAD' || m === 'DELETE' || !!idempotencyKey;
+}
+export class Transport {
+    baseUrl;
+    opts;
+    #fetch;
+    constructor(opts) {
+        this.baseUrl = (opts.baseUrl || DEFAULT_BASE_URL).replace(/\/$/, '');
+        if (opts.apiKey && opts.token)
+            throw new TypeError('VocalStack: pass apiKey (a server) or token (a browser), not both');
+        this.opts = opts;
+        this.#fetch = opts.fetch ?? globalThis.fetch.bind(globalThis);
+    }
+    async bearer() {
+        if (this.opts.apiKey)
+            return this.opts.apiKey;
+        const t = this.opts.token;
+        const v = typeof t === 'function' ? await t() : t;
+        return v ?? undefined;
+    }
+    url(path, query) {
+        return `${this.baseUrl}${path}${qs(query)}`;
+    }
+    wsUrl(path, query) {
+        return `${this.baseUrl.replace(/^http/, 'ws')}${path}${qs(query)}`;
+    }
+    async raw(method, path, init = {}) {
+        const headers = { accept: 'application/json', ...init.headers };
+        const form = typeof FormData !== 'undefined' && init.body instanceof FormData;
+        const urlencoded = init.body instanceof URLSearchParams;
+        if (urlencoded)
+            headers['content-type'] = 'application/x-www-form-urlencoded';
+        else if (init.body !== undefined && !form)
+            headers['content-type'] = 'application/json';
+        const token = init.anonymous ? undefined : await this.bearer();
+        if (token)
+            headers.authorization = `Bearer ${token}`;
+        if (this.opts.actingPrincipal)
+            headers['x-acting-principal'] = this.opts.actingPrincipal;
+        if (this.opts.deviceId)
+            headers['x-device-id'] = this.opts.deviceId;
+        if (init.idempotencyKey)
+            headers['idempotency-key'] = init.idempotencyKey;
+        const body = init.body === undefined ? undefined : form ? init.body : urlencoded ? String(init.body) : JSON.stringify(init.body);
+        const maxRetries = init.noRetry ? 0 : (this.opts.maxRetries ?? 2);
+        for (let attempt = 0;; attempt++) {
+            let res;
+            try {
+                res = await this.#fetch(this.url(path, init.query), {
+                    method,
+                    headers,
+                    body,
+                    redirect: 'manual',
+                    signal: init.signal,
+                });
+            }
+            catch (e) {
+                if (e?.name === 'AbortError')
+                    throw e;
+                const err = new VocalStackError('unavailable', 'could not reach the VocalStack API', { retryable: true });
+                err.cause = e;
+                throw err;
+            }
+            if (res.ok || (res.status >= 300 && res.status < 400))
+                return res;
+            const text = await res.text().catch(() => '');
+            let json = null;
+            try {
+                json = text ? JSON.parse(text) : null;
+            }
+            catch {
+                json = null;
+            }
+            const err = (init.oauthErrors ? fromOAuth : fromEnvelope)(json, res.status, res.headers);
+            if (retries(res.status, err.code, method, init.idempotencyKey) && attempt < maxRetries) {
+                const wait = err.retryAfter ?? (err.code === 'unavailable' ? UNAVAILABLE_WAIT_S : undefined);
+                if (wait !== undefined && wait <= 60) {
+                    await sleep(wait * 1000);
+                    continue;
+                }
+            }
+            throw err;
+        }
+    }
+    async json(method, path, init = {}) {
+        const res = await this.raw(method, path, init);
+        if (res.status >= 300 && res.status < 400)
+            return { location: res.headers.get('location') };
+        const text = await res.text();
+        if (!text)
+            return undefined;
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            throw new VocalStackError('internal', 'the API answered with a body that is not JSON', { status: res.status, headers: res.headers, requestId: res.headers.get('x-request-id') ?? undefined });
+        }
+    }
+}

package/dist/index.d.ts

@@ -1,2 +1,42 @@
-export * from './apis/index';
-export * from './generics.zod';
+import { type ClientOptions } from './http.js';
+import { Realtime } from './realtime.js';
+import { Batches, Billing, Broadcasts, Connect, Corrections, Events, Jobs, Languages, MeApi, Meta, Recordings, Rtmp, Search, ShareLinks, Tags, Transcriptions, Voices } from './resources.js';
+export type { ClientOptions, CallOptions, ReadAs, Query } from './http.js';
+export { DEFAULT_BASE_URL } from './http.js';
+export { VocalStackError } from './errors.js';
+export type { ConnectTokenErrorCode, VocalStackErrorOptions } from './errors.js';
+export { RealtimeSession } from './realtime.js';
+export type { ConnectParams, SessionEvent } from './realtime.js';
+export type { FileInput } from './file.js';
+export { Realtime, applySentence } from './realtime.js';
+export type { ConnectOptions, TranscribeOptions, RealtimeTranscript } from './realtime.js';
+export { Subscription } from './subscription.js';
+export type { SubscribeOptions, SubscriptionEvent } from './subscription.js';
+export type { WsLike } from './ws.js';
+export { Batches, Broadcasts, Connect, Corrections, Events, Jobs, Languages, MeApi, Meta, Recordings, Rtmp, Search, ShareLinks, Tags, Transcriptions, Voices, playableFormat, } from './resources.js';
+export type { AudioKind, MediaAuth, MediaFormat, RenderVoice } from './resources.js';
+export type { AddBatchFileInput, ConnectToken, ConnectTokenInput, CreateTranscriptionInput, LifecycleFilter, Me, PageOptions, RecordingPageOptions, SearchOptions, Upload, UsageChargesOptions, UsageOptions } from './resources.js';
+export type * from '@vocalstack/contract';
+export type VocalStackOptions = ClientOptions;
+export declare class VocalStack {
+    readonly baseUrl: string;
+    readonly realtime: Realtime;
+    readonly broadcasts: Broadcasts;
+    readonly transcriptions: Transcriptions;
+    readonly batches: Batches;
+    readonly recordings: Recordings;
+    readonly jobs: Jobs;
+    readonly corrections: Corrections;
+    readonly shareLinks: ShareLinks;
+    readonly tags: Tags;
+    readonly voices: Voices;
+    readonly search: Search;
+    readonly me: MeApi;
+    readonly connect: Connect;
+    readonly billing: Billing;
+    readonly languages: Languages;
+    readonly rtmp: Rtmp;
+    readonly events: Events;
+    readonly meta: Meta;
+    constructor(opts?: ClientOptions);
+}

package/dist/index.js

@@ -1,18 +1,52 @@
-"use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
+import { Transport } from './http.js';
+import { Realtime } from './realtime.js';
+import { Batches, Billing, Broadcasts, Connect, Corrections, Events, Jobs, Languages, MeApi, Meta, Recordings, Rtmp, Search, ShareLinks, Tags, Transcriptions, Voices, } from './resources.js';
+export { DEFAULT_BASE_URL } from './http.js';
+export { VocalStackError } from './errors.js';
+export { RealtimeSession } from './realtime.js';
+export { Realtime, applySentence } from './realtime.js';
+export { Subscription } from './subscription.js';
+export { Batches, Broadcasts, Connect, Corrections, Events, Jobs, Languages, MeApi, Meta, Recordings, Rtmp, Search, ShareLinks, Tags, Transcriptions, Voices, playableFormat, } from './resources.js';
+export class VocalStack {
+    baseUrl;
+    realtime;
+    broadcasts;
+    transcriptions;
+    batches;
+    recordings;
+    jobs;
+    corrections;
+    shareLinks;
+    tags;
+    voices;
+    search;
+    me;
+    connect;
+    billing;
+    languages;
+    rtmp;
+    events;
+    meta;
+    constructor(opts = {}) {
+        const t = new Transport(opts);
+        this.baseUrl = t.baseUrl;
+        this.realtime = new Realtime(t);
+        this.broadcasts = new Broadcasts(t);
+        this.transcriptions = new Transcriptions(t);
+        this.batches = new Batches(t);
+        this.recordings = new Recordings(t);
+        this.jobs = new Jobs(t);
+        this.corrections = new Corrections(t);
+        this.shareLinks = new ShareLinks(t);
+        this.tags = new Tags(t);
+        this.voices = new Voices(t);
+        this.search = new Search(t);
+        this.me = new MeApi(t);
+        this.connect = new Connect(t);
+        this.billing = new Billing(t);
+        this.languages = new Languages(t);
+        this.rtmp = new Rtmp(t);
+        this.events = new Events(t);
+        this.meta = new Meta(t);
     }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __exportStar = (this && this.__exportStar) || function(m, exports) {
-    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-__exportStar(require("./apis/index"), exports);
-__exportStar(require("./generics.zod"), exports);
+}

package/dist/mic.d.ts

@@ -0,0 +1,27 @@
+import type { RealtimeSession } from './realtime.js';
+export type MicStallReason = 'track_ended' | 'track_muted' | 'context_suspended' | 'context_closed' | 'silent';
+export interface MicCaptureOptions {
+    chunkSeconds?: number;
+    sampleRate?: number;
+    audio?: MediaTrackConstraints;
+    onClock?: (pcm: number, wall: number) => void;
+    onStall?: (reason: MicStallReason) => void;
+    onRecover?: () => void;
+    silentSeconds?: number;
+}
+export interface MicDevice {
+    label: string;
+    sampleRate?: number;
+    channelCount?: number;
+    noiseSuppression?: boolean;
+    echoCancellation?: boolean;
+}
+export interface MicCapture {
+    stop(): Promise<void>;
+    readonly sampleRate: number;
+    readonly device: MicDevice;
+    setMuted(muted: boolean): void;
+    readonly muted: boolean;
+}
+export declare function captureMicrophone(onChunk: (pcm: Float32Array) => void, opts?: MicCaptureOptions): Promise<MicCapture>;
+export declare function streamMicrophone(session: RealtimeSession, opts?: MicCaptureOptions): Promise<MicCapture>;

package/dist/mic.js

@@ -0,0 +1,236 @@
+const WORKLET_SOURCE = `
+class PCMProcessor extends AudioWorkletProcessor {
+  process(inputs) {
+    const input = inputs[0];
+    if (!input || input.length === 0) return true;
+    const ch = input[0];
+    if (!ch || ch.length === 0) return true;
+    this.port.postMessage(ch.slice(0));
+    return true;
+  }
+}
+registerProcessor('pcm-processor', PCMProcessor);
+`;
+const RECOVER_MS = 1000;
+const CLOCK_MS = 500;
+export async function captureMicrophone(onChunk, opts = {}) {
+    if (typeof navigator === 'undefined' || !navigator.mediaDevices) {
+        throw new Error('captureMicrophone is browser-only (no mediaDevices)');
+    }
+    const targetRate = opts.sampleRate ?? 16000;
+    const chunkSamples = Math.round((opts.chunkSeconds ?? 0.25) * targetRate);
+    const constraints = opts.audio ?? {
+        channelCount: 1,
+        echoCancellation: true,
+        noiseSuppression: true,
+    };
+    let muted = false;
+    let media = await navigator.mediaDevices.getUserMedia({ audio: constraints });
+    let ctx;
+    try {
+        ctx = new AudioContext({ sampleRate: targetRate });
+    }
+    catch {
+        ctx = new AudioContext();
+    }
+    const workletUrl = URL.createObjectURL(new Blob([WORKLET_SOURCE], { type: 'application/javascript' }));
+    try {
+        await ctx.audioWorklet.addModule(workletUrl);
+    }
+    finally {
+        URL.revokeObjectURL(workletUrl);
+    }
+    const node = new AudioWorkletNode(ctx, 'pcm-processor');
+    let source = ctx.createMediaStreamSource(media);
+    source.connect(node);
+    const inputRate = ctx.sampleRate;
+    const passThrough = inputRate === targetRate;
+    let buffered = [];
+    let readPos = 0;
+    let pending = null;
+    const t0 = performance.now();
+    let outSamples = 0;
+    const silentLimit = Math.round((opts.silentSeconds ?? 3) * inputRate);
+    let zeroRun = 0;
+    let silentFlagged = false;
+    let stopped = false;
+    let stall = null;
+    let recoverTimer = null;
+    const setStall = (reason) => {
+        if (stopped || stall === reason)
+            return;
+        stall = reason;
+        opts.onStall?.(reason);
+    };
+    const clearStall = () => {
+        if (stall === null)
+            return;
+        stall = null;
+        opts.onRecover?.();
+    };
+    node.port.onmessage = (ev) => {
+        const block = ev.data;
+        if (silentLimit > 0) {
+            let allZero = true;
+            for (const v of block) {
+                if (v !== 0) {
+                    allZero = false;
+                    break;
+                }
+            }
+            if (allZero) {
+                zeroRun += block.length;
+                if (!silentFlagged && zeroRun >= silentLimit) {
+                    silentFlagged = true;
+                    setStall('silent');
+                }
+            }
+            else {
+                zeroRun = 0;
+                if (silentFlagged) {
+                    silentFlagged = false;
+                    if (stall === 'silent')
+                        clearStall();
+                }
+            }
+        }
+        let out;
+        if (passThrough) {
+            out = block;
+        }
+        else {
+            for (const v of block)
+                buffered.push(v);
+            const step = inputRate / targetRate;
+            const res = [];
+            while (readPos + 1 < buffered.length) {
+                const i = Math.floor(readPos);
+                const frac = readPos - i;
+                res.push(buffered[i] * (1 - frac) + buffered[i + 1] * frac);
+                readPos += step;
+            }
+            const keepFrom = Math.max(0, Math.floor(readPos) - 1);
+            buffered = buffered.slice(keepFrom);
+            readPos -= keepFrom;
+            out = res;
+        }
+        if (out.length) {
+            outSamples += out.length;
+            if (stall !== null && stall !== 'silent')
+                clearStall();
+            pending = pending ? concat(pending, out) : Float32Array.from(out);
+            while (pending.length >= chunkSamples) {
+                const chunk = pending.slice(0, chunkSamples);
+                onChunk(muted ? new Float32Array(chunk.length) : chunk);
+                pending = pending.slice(chunkSamples);
+            }
+        }
+    };
+    const clockTimer = opts.onClock
+        ? setInterval(() => {
+            opts.onClock?.(outSamples, (performance.now() - t0) / 1000);
+        }, CLOCK_MS)
+        : null;
+    const scheduleRecover = (fn) => {
+        if (stopped || recoverTimer)
+            return;
+        recoverTimer = setTimeout(() => {
+            recoverTimer = null;
+            fn();
+        }, RECOVER_MS);
+    };
+    const resumeContext = () => {
+        if (stopped || ctx.state !== 'suspended')
+            return;
+        void ctx.resume().catch(() => { }).then(() => {
+            if (!stopped && ctx.state === 'suspended')
+                scheduleRecover(resumeContext);
+        });
+    };
+    const reacquireTrack = () => {
+        if (stopped)
+            return;
+        navigator.mediaDevices
+            .getUserMedia({ audio: constraints })
+            .then((next) => {
+            if (stopped) {
+                for (const t of next.getTracks())
+                    t.stop();
+                return;
+            }
+            source.disconnect();
+            for (const t of media.getTracks())
+                t.stop();
+            media = next;
+            source = ctx.createMediaStreamSource(media);
+            source.connect(node);
+            watchTracks(media);
+        })
+            .catch(() => scheduleRecover(reacquireTrack));
+    };
+    const watchTracks = (stream) => {
+        for (const track of stream.getAudioTracks()) {
+            track.addEventListener('ended', () => {
+                if (stopped)
+                    return;
+                setStall('track_ended');
+                scheduleRecover(reacquireTrack);
+            });
+            track.addEventListener('mute', () => {
+                if (!stopped)
+                    setStall('track_muted');
+            });
+        }
+    };
+    watchTracks(media);
+    ctx.addEventListener('statechange', () => {
+        if (stopped)
+            return;
+        if (ctx.state === 'suspended') {
+            setStall('context_suspended');
+            resumeContext();
+        }
+        else if (ctx.state === 'closed') {
+            setStall('context_closed');
+        }
+    });
+    return {
+        sampleRate: targetRate,
+        get device() {
+            const t = media.getAudioTracks()[0];
+            const st = (t?.getSettings?.() ?? {});
+            return { label: t?.label ?? '', sampleRate: st.sampleRate, channelCount: st.channelCount, noiseSuppression: st.noiseSuppression, echoCancellation: st.echoCancellation };
+        },
+        get muted() {
+            return muted;
+        },
+        setMuted(on) {
+            muted = !!on;
+        },
+        async stop() {
+            stopped = true;
+            if (clockTimer)
+                clearInterval(clockTimer);
+            if (recoverTimer)
+                clearTimeout(recoverTimer);
+            node.port.onmessage = null;
+            source.disconnect();
+            node.disconnect();
+            for (const t of media.getTracks())
+                t.stop();
+            await ctx.close();
+        },
+    };
+}
+export async function streamMicrophone(session, opts = {}) {
+    return captureMicrophone((pcm) => session.sendAudio(pcm), {
+        onClock: (pcm, wall) => session.sendClock(pcm, wall),
+        ...opts,
+    });
+}
+function concat(a, b) {
+    const out = new Float32Array(a.length + b.length);
+    out.set(a, 0);
+    out.set(b, a.length);
+    return out;
+}

package/dist/realtime.d.ts

@@ -0,0 +1,77 @@
+import type { Capabilities, CommittedSegment, CreateSessionResponse, Fix, LatencyMode, SentenceSegment, ServerFrame, SessionOptions, SessionStats, SpeakerLabels, WarmRequest } from '@vocalstack/contract';
+import { VocalStackError } from './errors.js';
+import { type FileInput } from './file.js';
+import type { CallOptions, Transport } from './http.js';
+export type SessionEvent = Extract<ServerFrame, {
+    type: 'transcript.committed' | 'transcript.draft' | 'transcript.words' | 'transcript.translated' | 'transcript.amended' | 'transcript.latency' | 'transcript.speaker' | 'transcript.sentence' | 'transcript.progress';
+}>;
+export interface ConnectParams {
+    sessionId: string;
+    streamUrl: string;
+    options?: SessionOptions;
+    readyDeadlineMs?: number;
+    onLoading?(stage: 'download' | 'model'): void;
+    onFrame?(frame: ServerFrame): void;
+}
+export declare function engineLost(closeCode?: number): VocalStackError;
+export declare function upgradeRefused(status: number | undefined, body: string): VocalStackError;
+export declare const RESTART_CLOSE = 1012;
+export declare class RealtimeSession implements AsyncIterable<SessionEvent> {
+    #private;
+    readonly sessionId: string;
+    private constructor();
+    static connect(params: ConnectParams): Promise<RealtimeSession>;
+    sendAudio(chunk: Float32Array | ArrayBuffer | Uint8Array): void;
+    sendFile(source: AsyncIterable<Uint8Array>, chunkBytes?: number): Promise<void>;
+    pipe(source: AsyncIterable<Float32Array | ArrayBuffer | Uint8Array> | ReadableStream<Uint8Array>): Promise<void>;
+    sendClock(pcm: number, wall: number): void;
+    update(changes: {
+        latencyMode?: LatencyMode;
+        spokenLanguage?: string;
+        speakerLabels?: SpeakerLabels;
+        translate?: string[];
+    }): void;
+    eof(): void;
+    cancel(): void;
+    get doneReason(): 'eof' | 'max_duration' | 'cancelled' | null;
+    get stats(): SessionStats | null;
+    close(): void;
+    [Symbol.asyncIterator](): AsyncIterator<SessionEvent>;
+    [Symbol.dispose](): void;
+}
+export interface ConnectOptions {
+    onLoading?(stage: 'download' | 'model'): void;
+    onFrame?(frame: ServerFrame): void;
+    readyDeadlineMs?: number;
+}
+export interface TranscribeOptions extends Omit<SessionOptions, 'input' | 'audio'> {
+    onSession?(session: RealtimeSession): void;
+    onProgress?(progress: {
+        processedS: number;
+        totalS?: number;
+    }): void;
+    onCommit?(segment: CommittedSegment): void;
+    onTranslated?(seq: number, translations: Record<string, string>, sources?: Record<string, string>): void;
+    onAmended?(seq: number, text: string, speaker: number, fixes: Fix[]): void;
+    onSpeakerSettled?(seq: number, speaker: number, verdict: string, confidence?: number): void;
+    onSentence?(sentence: SentenceSegment): void;
+    readyDeadlineMs?: number;
+}
+export interface RealtimeTranscript {
+    segments: CommittedSegment[];
+    sentences: SentenceSegment[];
+    text: string;
+    doneReason: 'eof' | 'max_duration' | 'cancelled' | null;
+    stats: SessionStats | null;
+}
+export declare class Realtime {
+    #private;
+    constructor(t: Transport);
+    createSession(options?: SessionOptions, call?: CallOptions): Promise<CreateSessionResponse>;
+    connect(options?: SessionOptions, connect?: ConnectOptions): Promise<RealtimeSession>;
+    capabilities(): Promise<Capabilities>;
+    warm(req: WarmRequest): Promise<void>;
+    transcribeFile(file: FileInput, opts?: TranscribeOptions): Promise<RealtimeTranscript>;
+    transcribeUrl(url: string, opts?: TranscribeOptions): Promise<RealtimeTranscript>;
+}
+export declare function applySentence(list: SentenceSegment[], sentence: SentenceSegment): SentenceSegment[];