@startsimpli/llm 0.4.29 → 0.4.31

package/src/speech/voices/cast-voices.ts

@@ -0,0 +1,169 @@
+import library from './cast-voices.json';
+import {
+  DuplicateVoiceError, ExpiringVoiceError, RetiredVoiceError, UnfilledVoiceSlotError, UnknownLanguageError,
+  UnknownModelError, VoiceNotResolvableError,
+} from './errors';
+import { repr } from '../repr';
+import { validateCastLibrary, type CastLibrary } from './schema';
+
+/** The shipped library, validated once at import. */
+export const defaultCastLibrary: CastLibrary = validateCastLibrary(library);
+
+export type ExpiringPolicy = 'warn' | 'allow' | 'error';
+
+export interface CastMember {
+  id: string;
+  /** A library id, or a real voice id. Anything else (a saved timeline's cast id, e.g. "maya") is an alias and ignored. */
+  voice?: string | null;
+  [extra: string]: unknown;
+}
+
+export interface VoiceSpec {
+  voiceId: string;
+  model: string;
+  settings: Record<string, number>;
+  /** The library entry the voice came from; null for a passed-through voice id. */
+  role: string | null;
+  /** The language row the voice was resolved for; null = the default language. */
+  language: string | null;
+}
+
+export interface CastVoicesOptions {
+  /** warn: warning until the deadline, then an error; allow: never complain; error: always an error. Default warn. */
+  expiring?: ExpiringPolicy;
+  /** The clock: `YYYY-MM-DD` or a Date. Default: now. */
+  today?: string | Date;
+  /** Receives each expiring-voice warning (once per voice). Default `console.warn`. */
+  onWarn?: (message: string) => void;
+}
+
+export interface ResolveOptions {
+  /** Overrides the entry's model (settings come from that model's block). */
+  model?: string | null;
+  language?: string | null;
+  /** The member's place among members without a voice of their own; `resolveCast` counts it. */
+  poolSlot?: number | null;
+}
+
+const isoDay = (d: string | Date) => (typeof d === 'string' ? d : d.toISOString()).slice(0, 10);
+const dayNumber = (iso: string) => Math.floor(Date.parse(`${iso}T00:00:00Z`) / 86_400_000);
+const has = (o: object | undefined, k: string | null | undefined): k is string => !!k && !!o && Object.prototype.hasOwnProperty.call(o, k);
+const get = (o: Record<string, any> | undefined, k: string | null | undefined) => (has(o, k) ? o![k] : undefined);
+const truthy = <T>(...xs: T[]) => xs.find((x) => (x && (typeof x !== 'object' || Object.keys(x as object).length > 0)) as boolean);
+
+export class CastVoices {
+  readonly warnings: string[] = [];
+  readonly deadline: string;
+  readonly today: string;
+  private readonly idPattern: RegExp;
+
+  constructor(readonly data: CastLibrary, private readonly options: CastVoicesOptions = {}) {
+    const policy = options.expiring ?? 'warn';
+    if (!['warn', 'allow', 'error'].includes(policy)) throw new Error(`expiring must be warn, allow or error, got ${repr(policy)}`);
+    this.policy = policy;
+    this.deadline = data.expiring_deadline ?? '2026-12-31';
+    this.today = isoDay(options.today ?? new Date());
+    this.idPattern = new RegExp(`^(?:${data.voice_id_pattern})$`);
+  }
+  private readonly policy: ExpiringPolicy;
+
+  get roles() { return this.data.roles; }
+
+  modelInfo(model: string) {
+    if (!has(this.data.models, model)) throw new UnknownModelError(`unknown model ${repr(model)}; known: ${repr(Object.keys(this.data.models).sort())}`);
+    return this.data.models[model];
+  }
+
+  /** True when the member names a library entry or a real voice id itself (not an alias, not nothing). */
+  hasVoiceRef(member: CastMember): boolean {
+    const v = member.voice;
+    return !!v && (has(this.roles, v) || this.idPattern.test(v));
+  }
+
+  /** [key, row] of the languages table for a tag (`es-MX` falls back to `es`); [null, null] for none or the default language. */
+  languageEntry(language?: string | null): [string | null, NonNullable<CastLibrary['languages']>[string] | null] {
+    if (!language) return [null, null];
+    const table = this.data.languages ?? {};
+    for (const key of [language, language.split('-')[0]]) {
+      if (has(table, key)) return table[key].default ? [null, null] : [key, table[key]];
+    }
+    throw new UnknownLanguageError(`language ${repr(language)} is not in the cast voice file; known: ${repr(Object.keys(table).sort())}`);
+  }
+
+  resolve(member: CastMember, opts: ResolveOptions = {}): VoiceSpec {
+    const voice = member.voice ?? null;
+    let role: string | null = has(this.roles, voice) ? voice : null;
+    const explicit = voice && role === null && this.idPattern.test(voice) ? voice : null;
+    const pool = this.data.default_pool ?? [];
+    if (role === null && explicit === null) {
+      if (opts.poolSlot == null || pool.length === 0) {
+        throw new VoiceNotResolvableError(
+          `cast member ${repr(member.id)}: no voice reference (${repr(voice)}) and no pool place; library: ${repr(Object.keys(this.roles).sort())}`);
+      }
+      role = pool[opts.poolSlot % pool.length];
+    }
+    const entry: Record<string, any> = role ? this.entry(role) : { model: this.data.default_model, settings: {} };
+    const [lang, row] = this.languageEntry(opts.language);
+    const own: Record<string, any> = (role && get(row?.roles, role)) || {};
+    const voiceId: string = explicit ?? own.voice_id ?? entry.voice_id;
+    this.checkAlive(voiceId);
+    const model: string = opts.model || own.model || row?.model || entry.model || this.data.default_model;
+    this.modelInfo(model);
+    const settings = { ...(truthy(get(own.settings, model), get(entry.settings, model)) ?? {}) } as Record<string, number>;
+    if (Object.keys(settings).length === 0 && !explicit) {
+      throw new VoiceNotResolvableError(`role ${repr(role)} has no settings for model ${repr(model)}`);
+    }
+    return { voiceId, model, settings, role, language: lang };
+  }
+
+  /** `{cast id: VoiceSpec}`; two members on one voice id throw (they would sound like one person). */
+  resolveCast(cast: CastMember[], opts: Omit<ResolveOptions, 'poolSlot'> = {}): Record<string, VoiceSpec> {
+    const out: Record<string, VoiceSpec> = {};
+    const seen = new Map<string, string>();
+    let slot = 0;
+    for (const member of cast) {
+      const ref = this.hasVoiceRef(member);
+      const spec = this.resolve(member, { ...opts, poolSlot: ref ? null : slot });
+      if (!ref) slot += 1;
+      if (seen.has(spec.voiceId)) {
+        throw new DuplicateVoiceError(`cast members ${repr(seen.get(spec.voiceId))} and ${repr(member.id)} resolve to the same voice ${spec.voiceId}`);
+      }
+      seen.set(spec.voiceId, member.id);
+      out[member.id] = spec;
+    }
+    return out;
+  }
+
+  /** The emotion mapping entry for a spec; a role's own emotion_map replaces the global one; unknown -> neutral. */
+  emotionEntry(spec: VoiceSpec, emotion: string): { tag?: string | null; settings_delta?: Record<string, number> } {
+    const own = get(this.roles, spec.role)?.emotion_map;
+    const table = (own ?? this.data.emotion_map).emotions;
+    return get(table, emotion) ?? table.neutral ?? { tag: null, settings_delta: {} };
+  }
+
+  private entry(role: string) {
+    const entry = this.roles[role];
+    if (!entry.voice_id) {
+      throw new UnfilledVoiceSlotError(`voice slot ${repr(role)} is empty: ${entry.fill ?? 'fill voice_id in the cast voice config'}`);
+    }
+    return entry;
+  }
+
+  private checkAlive(voiceId: string): void {
+    const retired = get(this.data.retired_voice_ids, voiceId);
+    if (retired !== undefined) throw new RetiredVoiceError(`voice ${voiceId} is retired: ${retired}`);
+    const name = get(this.data.default_voice_ids_expiring_2026_12_31, voiceId);
+    if (name === undefined) return;
+    const what = `voice ${voiceId} (${name}) is a Default voice that expires ${this.deadline}`;
+    if (this.policy === 'error' || (this.policy === 'warn' && this.today >= this.deadline)) throw new ExpiringVoiceError(what);
+    if (this.policy === 'warn' && !this.warnings.includes(what)) {
+      this.warnings.push(what);
+      const days = dayNumber(this.deadline) - dayNumber(this.today);
+      (this.options.onWarn ?? ((m) => console.warn(m)))(`${what} (${days} days left): pick a replacement or a clone before then`);
+    }
+  }
+}
+
+export function createCastVoices(data: CastLibrary = defaultCastLibrary, options: CastVoicesOptions = {}): CastVoices {
+  return new CastVoices(data, options);
+}

package/src/speech/voices/emotion.ts

@@ -0,0 +1,51 @@
+import type { CastVoices, VoiceSpec } from './cast-voices';
+import { stripTags } from './tags';
+
+export type EmotionMode = 'tags' | 'cli' | 'off';
+const MODES: EmotionMode[] = ['tags', 'cli', 'off'];
+
+export interface Direction {
+  /** What the vendor speaks (may start with a tag). */
+  textSent: string;
+  /** `textSent` without tags: for captions, cues and word counts. */
+  spokenText: string;
+  settings: Record<string, number>;
+  model: string;
+  /** Mode `cli`: the speech CLI applies the emotion itself. */
+  cliEmotion: string | null;
+}
+
+const neutral = (key: string) => (key === 'speed' ? 1.0 : 0.5);
+const round4 = (n: number) => Math.round(n * 1e4) / 1e4;
+
+function clamped(cv: CastVoices, base: Record<string, number>, delta: Record<string, number>) {
+  const out = { ...base };
+  for (const [k, d] of Object.entries(delta)) {
+    const [lo, hi] = cv.data.settings_limits[k];
+    out[k] = round4(Math.min(hi, Math.max(lo, (out[k] ?? neutral(k)) + d)));
+  }
+  return out;
+}
+
+/**
+ * Timeline emotion -> voice direction. Tag models get an audio tag in front of the text; other models get a settings
+ * delta (clamped to the library's limits). The tag is sent to the vendor and billed, and never belongs in captions.
+ */
+export function directEmotion(cv: CastVoices, spec: VoiceSpec, text: string, emotion: string | null | undefined, mode?: EmotionMode): Direction {
+  const m = mode ?? cv.data.emotion_mode_default ?? 'tags';
+  if (!MODES.includes(m)) throw new Error(`emotion mode ${JSON.stringify(m)} not in ${MODES.join(', ')}`);
+  const spokenText = stripTags(text, cv.data.tag_pattern);
+  const plain: Direction = { textSent: text, spokenText, settings: { ...spec.settings }, model: spec.model, cliEmotion: null };
+  if (m === 'off' || emotion == null) return plain;
+  const entry = cv.emotionEntry(spec, emotion);
+  const delta = entry.settings_delta ?? {};
+  if (m === 'cli') {
+    return { ...plain, cliEmotion: entry.tag || Object.keys(delta).length ? emotion : null };
+  }
+  const hasTags = cv.modelInfo(spec.model).tags;
+  let textSent = text;
+  let settings = { ...spec.settings };
+  if (hasTags && entry.tag && text === spokenText) textSent = `${entry.tag} ${text}`;
+  if ((!hasTags || cv.data.emotion_map.tag_models_use_delta) && Object.keys(delta).length) settings = clamped(cv, settings, delta);
+  return { textSent, spokenText, settings, model: spec.model, cliEmotion: null };
+}

package/src/speech/voices/errors.ts

@@ -0,0 +1,14 @@
+import { repr } from '../repr';
+
+/** Named failures of voice resolution. All extend `VoiceNotResolvableError`, so one catch covers them. */
+export class VoiceNotResolvableError extends Error {
+  /** Machine-readable kind, stable across the CLI and the Python side. */
+  readonly kind: string = 'not_resolvable';
+  constructor(message: string) { super(message); this.name = new.target.name; }
+}
+export class UnfilledVoiceSlotError extends VoiceNotResolvableError { readonly kind = 'unfilled'; }
+export class RetiredVoiceError extends VoiceNotResolvableError { readonly kind = 'retired'; }
+export class ExpiringVoiceError extends VoiceNotResolvableError { readonly kind = 'expiring'; }
+export class UnknownModelError extends VoiceNotResolvableError { readonly kind = 'unknown_model'; }
+export class UnknownLanguageError extends VoiceNotResolvableError { readonly kind = 'unknown_language'; }
+export class DuplicateVoiceError extends VoiceNotResolvableError { readonly kind = 'duplicate_voice'; }

package/src/speech/voices/index.ts

@@ -0,0 +1,12 @@
+/** Voice cast library: neutral voice ids, voice-id resolution, expiring/retired Default-voice awareness, emotion direction. */
+export { CastVoices, createCastVoices, defaultCastLibrary } from './cast-voices';
+export type { CastMember, CastVoicesOptions, ExpiringPolicy, ResolveOptions, VoiceSpec } from './cast-voices';
+export { castLibrarySchema, validateCastLibrary } from './schema';
+export type { CastLibrary } from './schema';
+export { directEmotion } from './emotion';
+export type { Direction, EmotionMode } from './emotion';
+export { stripTags } from './tags';
+export {
+  DuplicateVoiceError, ExpiringVoiceError, RetiredVoiceError, UnfilledVoiceSlotError, UnknownLanguageError,
+  UnknownModelError, VoiceNotResolvableError,
+} from './errors';

package/src/speech/voices/schema.ts

@@ -0,0 +1,53 @@
+import { z } from 'zod';
+
+const settings = z.record(z.string(), z.number());
+const perModel = z.record(z.string(), settings);
+
+const emotionEntry = z.object({ tag: z.string().nullable().optional(), settings_delta: z.record(z.string(), z.number()).optional() });
+const emotionTable = z.object({ about: z.string().optional(), emotions: z.record(z.string(), emotionEntry) });
+
+const role = z.object({
+  name: z.string().optional(),
+  voice_id: z.string().nullable(),
+  kind: z.string().optional(),
+  model: z.string().optional(),
+  settings: perModel.optional(),
+  fill: z.string().optional(),
+  stand_in_for: z.string().optional(),
+  emotion_map: emotionTable.optional(),
+});
+
+const languageRow = z.object({
+  default: z.boolean().optional(),
+  model: z.string().optional(),
+  rhubarb_recognizer: z.string().optional(),
+  roles: z.record(z.string(), z.object({ voice_id: z.string().optional(), model: z.string().optional(), settings: perModel.optional() })).optional(),
+});
+
+/**
+ * The cast voice library: voices keyed by NEUTRAL id (never by avatar), models, emotion mapping, languages, and the
+ * retired / expiring ElevenLabs voice ids. Data only; no keys. Snake_case keys are the file format, shared with Python.
+ */
+export const castLibrarySchema = z.object({
+  version: z.number().optional(),
+  about: z.string().optional(),
+  default_model: z.string(),
+  models: z.record(z.string(), z.object({ tags: z.boolean(), usd_per_1k_chars: z.number().optional(), price_source: z.string().optional() })),
+  tag_pattern: z.string(),
+  voice_id_pattern: z.string(),
+  settings_limits: z.record(z.string(), z.tuple([z.number(), z.number()])),
+  emotion_mode_default: z.enum(['tags', 'cli', 'off']).optional(),
+  emotion_map: emotionTable.extend({ tag_models_use_delta: z.boolean().optional() }),
+  languages: z.record(z.string(), languageRow).optional(),
+  default_pool: z.array(z.string()).optional(),
+  roles: z.record(z.string(), role),
+  retired_voice_ids: z.record(z.string(), z.string()),
+  expiring_deadline: z.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional(),
+  default_voice_ids_expiring_2026_12_31: z.record(z.string(), z.string()),
+}).passthrough();
+
+export type CastLibrary = z.infer<typeof castLibrarySchema>;
+
+export function validateCastLibrary(data: unknown): CastLibrary {
+  return castLibrarySchema.parse(data);
+}

package/src/speech/voices/tags.ts

@@ -0,0 +1,11 @@
+import library from './cast-voices.json';
+
+/** Audio tags (`[excited]`, `[sighs]`) the tag-capable models speak. The pattern is library data. */
+export function tagPattern(tagPatternSource: string = library.tag_pattern): RegExp {
+  return new RegExp(tagPatternSource, 'g');
+}
+
+/** Text without any [tag], whitespace collapsed to single spaces. Idempotent. */
+export function stripTags(text: string, tagPatternSource?: string): string {
+  return text.replace(tagPattern(tagPatternSource), ' ').split(/\s+/).filter(Boolean).join(' ');
+}

package/src/speech/voices-cli.ts

@@ -0,0 +1,43 @@
+import { readFile } from 'node:fs/promises';
+
+import { VoiceNotResolvableError } from './voices/errors';
+import { createCastVoices, defaultCastLibrary, type CastMember, type ExpiringPolicy } from './voices';
+import { validateCastLibrary } from './voices/schema';
+
+/** Outcome shape shared with `cli.ts`. Kept here so the voices command stays out of that file. */
+export interface VoicesOutcome { exitCode: 0 | 1 | 2; output: unknown }
+
+class VoicesUsageError extends Error {}
+
+/**
+ * `startsimpli-speech voices resolve` — cast members in, voice specs out (snake_case, the Python resolver's shape):
+ *   {"cast":[{"id":"maya","voice":"presenter"}], "model"?, "language"?, "expiring"?, "today"?, "library"?}
+ * Flags --library FILE, --model, --language, --expiring warn|allow|error, --today YYYY-MM-DD override the request.
+ * Output `{voices: {id: {voice_id, model, settings, role, language}}, warnings: []}`; a resolution failure is
+ * `{error: {kind, message}, warnings}` with exit 1.
+ */
+export async function runVoices(sub: string | undefined, body: Record<string, any>, flags: Record<string, string>): Promise<VoicesOutcome> {
+  try {
+    if (sub !== 'resolve') throw new VoicesUsageError('usage: startsimpli-speech voices resolve [--in request.json] [--library FILE] [--model ID] [--language CODE] [--expiring warn|allow|error] [--today YYYY-MM-DD]');
+    if (!Array.isArray(body.cast)) throw new VoicesUsageError('voices resolve needs "cast": [{"id", "voice"?}] in the request');
+    const expiring = (flags.expiring ?? body.expiring ?? 'warn') as ExpiringPolicy;
+    if (!['warn', 'allow', 'error'].includes(expiring)) throw new VoicesUsageError(`--expiring must be warn, allow or error, got "${expiring}"`);
+    const today = flags.today ?? body.today;
+    if (today !== undefined && !/^\d{4}-\d{2}-\d{2}$/.test(today)) throw new VoicesUsageError('--today must be YYYY-MM-DD');
+    const raw = flags.library ? JSON.parse(await readFile(flags.library, 'utf8')) : body.library;
+    const library = raw ? validateCastLibrary(raw) : defaultCastLibrary;
+    const cv = createCastVoices(library, { expiring, today, onWarn: (m) => process.stderr.write(`${m}\n`) });
+    try {
+      const specs = cv.resolveCast(body.cast as CastMember[], { model: flags.model ?? body.model, language: flags.language ?? body.language });
+      const voices = Object.fromEntries(Object.entries(specs).map(([id, s]) => [id, {
+        voice_id: s.voiceId, model: s.model, settings: s.settings, role: s.role, language: s.language,
+      }]));
+      return { exitCode: 0, output: { voices, warnings: cv.warnings } };
+    } catch (error) {
+      if (!(error instanceof VoiceNotResolvableError)) throw error;
+      return { exitCode: 1, output: { error: { code: 'VOICE_NOT_RESOLVABLE', kind: error.kind, message: error.message }, warnings: cv.warnings } };
+    }
+  } catch (error) {
+    return { exitCode: 2, output: { error: { code: 'USAGE', message: (error as Error).message } } };
+  }
+}