egaki 0.6.0 → 0.7.1

package/src/cli/clone-generate.ts

@@ -0,0 +1,202 @@
+// Voice cloning via Cartesia and ElevenLabs APIs.
+// Both are simple multipart/form-data HTTP calls, no SDK needed.
+// Returns Error | Result (errore style) instead of throwing.
+//
+// Cartesia: POST https://api.cartesia.ai/voices/clone
+//   Instant clone, up to 10s of audio, free.
+//   Docs: https://docs.cartesia.ai/api-reference/voices/clone
+//   Best practices: https://docs.cartesia.ai/build-with-cartesia/capability-guides/clone-voices
+//
+// ElevenLabs: POST https://api.elevenlabs.io/v1/voices/add
+//   Instant voice clone (IVC), 1-3 min recommended.
+//   Docs: https://elevenlabs.io/docs/api-reference/voices/ivc/create
+import { injectCredentialsToEnv } from './credentials.js'
+
+// ─── types ──────────────────────────────────────────────────────────────────
+
+export type CloneProvider = 'cartesia' | 'elevenlabs'
+
+export interface CloneVoiceOptions {
+  /** Raw audio bytes of the clip to clone from. */
+  audio: Uint8Array
+  /** Name for the cloned voice. */
+  name: string
+  /** Which provider to use. */
+  provider: CloneProvider
+  /** Cartesia only: ISO 639-1 language code. Default: 'en'. Ignored by ElevenLabs. */
+  language?: string
+  /** Optional description for the voice. */
+  description?: string
+  /** Original filename for MIME type inference. */
+  filename?: string
+  /** Cartesia: optional base voice ID to derive from. */
+  baseVoiceId?: string
+  /** ElevenLabs: apply AI noise removal to the clip. */
+  removeBackgroundNoise?: boolean
+}
+
+export interface CloneVoiceResult {
+  voiceId: string
+  name: string
+  provider: CloneProvider
+}
+
+// ─── validation ─────────────────────────────────────────────────────────────
+
+const CARTESIA_LANGUAGES = new Set([
+  'en', 'fr', 'de', 'es', 'pt', 'zh', 'ja', 'hi', 'it', 'ko', 'nl', 'pl',
+  'ru', 'sv', 'tr', 'tl', 'bg', 'ro', 'ar', 'cs', 'el', 'fi', 'hr', 'ms',
+  'sk', 'da', 'ta', 'uk', 'hu', 'no', 'vi', 'bn', 'th', 'he', 'ka', 'id',
+  'te', 'gu', 'kn', 'ml', 'mr', 'pa',
+])
+
+function validateOptions(opts: CloneVoiceOptions): Error | void {
+  if (opts.audio.length === 0) {
+    return new Error('No audio data provided. Pass an audio file or use --stdin.')
+  }
+  if (!opts.name || opts.name.trim().length === 0) {
+    return new Error('Voice name is required. Use --name "My Voice".')
+  }
+  if (opts.provider === 'cartesia' && opts.language && !CARTESIA_LANGUAGES.has(opts.language)) {
+    return new Error(
+      `Unsupported language "${opts.language}" for Cartesia. ` +
+      `Supported: ${[...CARTESIA_LANGUAGES].join(', ')}`,
+    )
+  }
+}
+
+// ─── MIME type helper ───────────────────────────────────────────────────────
+
+function mimeTypeFromFilename(filename?: string): string {
+  if (!filename) return 'audio/mpeg'
+  const ext = filename.split('.').pop()?.toLowerCase()
+  const map: Record<string, string> = {
+    mp3: 'audio/mpeg',
+    wav: 'audio/wav',
+    flac: 'audio/flac',
+    ogg: 'audio/ogg',
+    oga: 'audio/ogg',
+    webm: 'audio/webm',
+    mpga: 'audio/mpeg',
+    m4a: 'audio/mp4',
+  }
+  return map[ext ?? ''] ?? 'audio/mpeg'
+}
+
+// ─── Cartesia clone ─────────────────────────────────────────────────────────
+
+const CARTESIA_API_BASE = 'https://api.cartesia.ai'
+const CARTESIA_API_VERSION = '2026-03-01'
+
+async function cloneVoiceCartesia(opts: CloneVoiceOptions): Promise<Error | CloneVoiceResult> {
+  const apiKey = process.env['CARTESIA_API_KEY']
+  if (!apiKey) {
+    return new Error(
+      'CARTESIA_API_KEY not found. Run: egaki login --provider cartesia\n' +
+      'Get your key at https://play.cartesia.ai/keys',
+    )
+  }
+
+  const language = opts.language ?? 'en'
+  const mime = mimeTypeFromFilename(opts.filename)
+  const ext = opts.filename?.split('.').pop() ?? 'mp3'
+
+  const formData = new FormData()
+  const blob = new Blob([Buffer.from(opts.audio)], { type: mime })
+  formData.append('clip', new File([blob], `clip.${ext}`, { type: mime }))
+  formData.append('name', opts.name.trim())
+  formData.append('language', language)
+  if (opts.description) formData.append('description', opts.description)
+  if (opts.baseVoiceId) formData.append('base_voice_id', opts.baseVoiceId)
+
+  const response = await fetch(`${CARTESIA_API_BASE}/voices/clone`, {
+    method: 'POST',
+    headers: {
+      'Cartesia-Version': CARTESIA_API_VERSION,
+      'Authorization': `Bearer ${apiKey}`,
+    },
+    body: formData,
+  }).catch((cause) => new Error('Cartesia clone request failed', { cause }))
+  if (response instanceof Error) return response
+
+  if (!response.ok) {
+    const errorText = await response.text().catch(() => '')
+    return new Error(`Cartesia clone API error ${response.status}: ${errorText || response.statusText}`)
+  }
+
+  const json = await response.json().catch(
+    (cause) => new Error('Cartesia clone API returned invalid JSON', { cause }),
+  ) as { id?: string; name?: string } | Error
+  if (json instanceof Error) return json
+  if (!json.id) return new Error('Cartesia clone API response did not include a voice id')
+  return {
+    voiceId: json.id,
+    name: json.name ?? opts.name.trim(),
+    provider: 'cartesia',
+  }
+}
+
+// ─── ElevenLabs clone ───────────────────────────────────────────────────────
+
+const ELEVENLABS_API_BASE = 'https://api.elevenlabs.io'
+
+async function cloneVoiceElevenLabs(opts: CloneVoiceOptions): Promise<Error | CloneVoiceResult> {
+  const apiKey = process.env['ELEVENLABS_API_KEY']
+  if (!apiKey) {
+    return new Error(
+      'ELEVENLABS_API_KEY not found. Run: egaki login --provider elevenlabs\n' +
+      'Get your key at https://elevenlabs.io/app/settings/api-keys',
+    )
+  }
+
+  const mime = mimeTypeFromFilename(opts.filename)
+  const ext = opts.filename?.split('.').pop() ?? 'mp3'
+
+  const formData = new FormData()
+  formData.append('name', opts.name.trim())
+  const blob = new Blob([Buffer.from(opts.audio)], { type: mime })
+  formData.append('files', new File([blob], `clip.${ext}`, { type: mime }))
+  if (opts.description) formData.append('description', opts.description)
+  if (opts.removeBackgroundNoise) formData.append('remove_background_noise', 'true')
+
+  const response = await fetch(`${ELEVENLABS_API_BASE}/v1/voices/add`, {
+    method: 'POST',
+    headers: {
+      'xi-api-key': apiKey,
+    },
+    body: formData,
+  }).catch((cause) => new Error('ElevenLabs clone request failed', { cause }))
+  if (response instanceof Error) return response
+
+  if (!response.ok) {
+    const errorText = await response.text().catch(() => '')
+    return new Error(`ElevenLabs clone API error ${response.status}: ${errorText || response.statusText}`)
+  }
+
+  const json = await response.json().catch(
+    (cause) => new Error('ElevenLabs clone API returned invalid JSON', { cause }),
+  ) as { voice_id?: string; requires_verification?: boolean } | Error
+  if (json instanceof Error) return json
+  if (!json.voice_id) return new Error('ElevenLabs clone API response did not include a voice_id')
+  return {
+    voiceId: json.voice_id,
+    name: opts.name.trim(),
+    provider: 'elevenlabs',
+  }
+}
+
+// ─── main entry point ───────────────────────────────────────────────────────
+
+export async function cloneVoiceUncached(
+  opts: CloneVoiceOptions,
+): Promise<Error | CloneVoiceResult> {
+  injectCredentialsToEnv()
+
+  const validationError = validateOptions(opts)
+  if (validationError) return validationError
+
+  if (opts.provider === 'elevenlabs') {
+    return cloneVoiceElevenLabs(opts)
+  }
+  return cloneVoiceCartesia(opts)
+}

package/src/{credentials.ts → cli/credentials.ts}

@@ -69,6 +69,26 @@ export const PROVIDERS: Record<string, ProviderInfo> = {
     hint: 'Sign in with your xAI / Grok account via browser',
     oauth: true,
   },
+  elevenlabs: {
+    envVar: 'ELEVENLABS_API_KEY',
+    label: 'ElevenLabs (speech)',
+    hint: 'Get your key at https://elevenlabs.io/app/settings/api-keys',
+  },
+  cartesia: {
+    envVar: 'CARTESIA_API_KEY',
+    label: 'Cartesia (speech)',
+    hint: 'Get your key at https://play.cartesia.ai/keys',
+  },
+  deepgram: {
+    envVar: 'DEEPGRAM_API_KEY',
+    label: 'Deepgram (transcription)',
+    hint: 'Get your key at https://console.deepgram.com/api-keys',
+  },
+  groq: {
+    envVar: 'GROQ_API_KEY',
+    label: 'Groq (fast transcription)',
+    hint: 'Get your key at https://console.groq.com/keys',
+  },
 }
 
 export const EGAKI_GATEWAY_URL = 'https://egaki.org/v3/ai'

package/src/cli/elevenlabs-speech-provider.ts

@@ -0,0 +1,243 @@
+// ElevenLabs speech provider for egaki.
+// Uses the streaming endpoint /v1/text-to-speech/{voiceId}/stream/with-timestamps
+// to get audio chunks + character timestamps in a single streamed response.
+// Character-level alignment is grouped into word-level timestamps.
+//
+// API docs: https://elevenlabs.io/docs/api-reference/text-to-speech/stream-with-timestamps
+//
+// The streaming response is NDJSON (newline-delimited JSON), NOT SSE.
+// Each line is a JSON object: { audio_base64, alignment?, normalized_alignment? }
+// Alignment data (character-level timing) is included in the first chunk only.
+// We use `normalized_alignment` (timing of what was actually spoken).
+
+import type { SpeechProvider, SpeechProviderOptions, SpeechProviderResult } from './speech-generate.js'
+import type { WordTimestamp } from './transcription-generate.js'
+
+const ELEVENLABS_API_BASE = 'https://api.elevenlabs.io'
+const DEFAULT_VOICE_ID = '21m00Tcm4TlvDq8ikWAM' // Rachel
+
+// ─── format mapping ──────────────────────────────────────────────────────────
+
+const FORMAT_MAP: Record<string, string> = {
+  mp3: 'mp3_44100_128',
+  mp3_32: 'mp3_44100_32',
+  mp3_64: 'mp3_44100_64',
+  mp3_96: 'mp3_44100_96',
+  mp3_128: 'mp3_44100_128',
+  mp3_192: 'mp3_44100_192',
+  pcm: 'pcm_44100',
+  pcm_16000: 'pcm_16000',
+  pcm_22050: 'pcm_22050',
+  pcm_24000: 'pcm_24000',
+  pcm_44100: 'pcm_44100',
+  ulaw: 'ulaw_8000',
+}
+
+function resolveOutputFormat(format?: string): string {
+  if (!format) return 'mp3_44100_128'
+  return FORMAT_MAP[format] || format
+}
+
+function formatToMediaType(format: string): string {
+  if (format.startsWith('mp3')) return 'audio/mpeg'
+  if (format.startsWith('pcm')) return 'audio/pcm'
+  if (format.startsWith('ulaw')) return 'audio/basic'
+  if (format.startsWith('opus')) return 'audio/opus'
+  if (format.startsWith('wav')) return 'audio/wav'
+  return 'audio/mpeg'
+}
+
+// ─── character-to-word grouping ──────────────────────────────────────────────
+
+interface CharacterAlignment {
+  characters: string[]
+  character_start_times_seconds: number[]
+  character_end_times_seconds: number[]
+}
+
+/**
+ * Group character-level timestamps into word-level timestamps.
+ * Characters are grouped by splitting on whitespace characters.
+ * Each word's start time is the start of its first character,
+ * and its end time is the end of its last character.
+ */
+export function groupCharactersToWords(alignment: CharacterAlignment): WordTimestamp[] {
+  const words: WordTimestamp[] = []
+  let currentWord = ''
+  let wordStart = -1
+  let wordEnd = -1
+
+  for (let i = 0; i < alignment.characters.length; i++) {
+    const char = alignment.characters[i]!
+    const charStart = alignment.character_start_times_seconds[i]!
+    const charEnd = alignment.character_end_times_seconds[i]!
+
+    if (/\s/.test(char)) {
+      if (currentWord) {
+        words.push({ word: currentWord, startSecond: wordStart, endSecond: wordEnd })
+        currentWord = ''
+        wordStart = -1
+        wordEnd = -1
+      }
+      continue
+    }
+
+    currentWord += char
+    if (wordStart < 0) wordStart = charStart
+    wordEnd = charEnd
+  }
+
+  if (currentWord) {
+    words.push({ word: currentWord, startSecond: wordStart, endSecond: wordEnd })
+  }
+
+  return words
+}
+
+// ─── NDJSON stream types ─────────────────────────────────────────────────────
+
+interface ElevenLabsStreamChunk {
+  audio_base64: string
+  alignment?: CharacterAlignment | null
+  normalized_alignment?: CharacterAlignment | null
+}
+
+// ─── NDJSON stream parser ────────────────────────────────────────────────────
+
+/**
+ * Parse an ElevenLabs NDJSON stream into audio chunks and character alignment.
+ * Each line is a JSON object with audio_base64 and optional alignment data.
+ * Alignment is typically only in the first chunk.
+ */
+export async function parseElevenLabsStream(
+  body: ReadableStream<Uint8Array>,
+): Promise<{ audioChunks: Uint8Array[]; alignment?: CharacterAlignment }> {
+  const audioChunks: Uint8Array[] = []
+  let alignment: CharacterAlignment | undefined
+
+  const reader = body.pipeThrough(new TextDecoderStream() as any).getReader()
+  let buffer = ''
+
+  while (true) {
+    const { done, value } = await reader.read()
+    if (done) break
+    buffer += value
+
+    // Process complete lines
+    let newlineIdx: number
+    while ((newlineIdx = buffer.indexOf('\n')) >= 0) {
+      const line = buffer.slice(0, newlineIdx).trim()
+      buffer = buffer.slice(newlineIdx + 1)
+      if (!line) continue
+
+      let chunk: ElevenLabsStreamChunk
+      try {
+        chunk = JSON.parse(line)
+      } catch {
+        continue
+      }
+
+      if (chunk.audio_base64) {
+        audioChunks.push(new Uint8Array(Buffer.from(chunk.audio_base64, 'base64')))
+      }
+
+      // Capture alignment from first chunk that has it
+      if (!alignment) {
+        const align = chunk.normalized_alignment || chunk.alignment
+        if (align) alignment = align
+      }
+    }
+  }
+
+  // Process any remaining data in buffer (last line without trailing newline)
+  const remaining = buffer.trim()
+  if (remaining) {
+    try {
+      const chunk: ElevenLabsStreamChunk = JSON.parse(remaining)
+      if (chunk.audio_base64) {
+        audioChunks.push(new Uint8Array(Buffer.from(chunk.audio_base64, 'base64')))
+      }
+      if (!alignment) {
+        const align = chunk.normalized_alignment || chunk.alignment
+        if (align) alignment = align
+      }
+    } catch { /* ignore malformed trailing data */ }
+  }
+
+  return { audioChunks, alignment }
+}
+
+/** Concatenate multiple Uint8Array chunks into one. */
+function concatUint8Arrays(chunks: Uint8Array[]): Uint8Array {
+  const totalLength = chunks.reduce((sum, c) => sum + c.length, 0)
+  const result = new Uint8Array(totalLength)
+  let offset = 0
+  for (const chunk of chunks) {
+    result.set(chunk, offset)
+    offset += chunk.length
+  }
+  return result
+}
+
+// ─── provider ────────────────────────────────────────────────────────────────
+
+export function createElevenLabsSpeechProvider(): SpeechProvider {
+  return {
+    async generate(options: SpeechProviderOptions): Promise<SpeechProviderResult> {
+      const apiKey = process.env['ELEVENLABS_API_KEY']
+      if (!apiKey) {
+        throw new Error('Missing ELEVENLABS_API_KEY. Run: egaki login --provider elevenlabs --key <key>')
+      }
+
+      const voiceId = options.voice || DEFAULT_VOICE_ID
+      const outputFormat = resolveOutputFormat(options.outputFormat)
+
+      const body: Record<string, unknown> = {
+        text: options.text,
+        model_id: options.modelId,
+      }
+
+      if (options.language) {
+        body.language_code = options.language
+      }
+
+      if (options.speed != null) {
+        body.voice_settings = { speed: options.speed }
+      }
+
+      const queryParams = new URLSearchParams({ output_format: outputFormat })
+      const url = `${ELEVENLABS_API_BASE}/v1/text-to-speech/${voiceId}/stream/with-timestamps?${queryParams}`
+
+      const response = await fetch(url, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'xi-api-key': apiKey,
+        },
+        body: JSON.stringify(body),
+        signal: options.abortSignal,
+      })
+
+      if (!response.ok) {
+        const errorText = await response.text().catch(() => '')
+        throw new Error(
+          `ElevenLabs TTS API error ${response.status}: ${errorText || response.statusText}`,
+        )
+      }
+
+      if (!response.body) {
+        throw new Error('ElevenLabs TTS stream response has no body')
+      }
+
+      const { audioChunks, alignment } = await parseElevenLabsStream(response.body)
+      const audio = concatUint8Arrays(audioChunks)
+      const timestamps = alignment ? groupCharactersToWords(alignment) : undefined
+
+      return {
+        audio,
+        mediaType: formatToMediaType(outputFormat),
+        timestamps,
+      }
+    },
+  }
+}

package/src/cli/generate.test.ts

@@ -0,0 +1,166 @@
+// Tests for the programmatic generation API (generate.ts).
+// Tests the error-as-value pattern and validation logic without
+// making actual API calls (no credentials needed).
+import { describe, it, expect } from 'vitest'
+import {
+  generateImage,
+  generateVideo,
+  calculateCost,
+  buildImageProviderOptions,
+  buildVideoProviderOptions,
+  ValidationError,
+} from './generate.js'
+
+describe('generateImage', () => {
+  it('returns ValidationError for unknown model', async () => {
+    const result = await generateImage({
+      prompt: 'test',
+      model: 'nonexistent-model-xyz',
+    })
+    expect(result).toBeInstanceOf(ValidationError)
+    expect((result as Error).message).toMatch(/Unknown model/)
+  })
+})
+
+describe('generateVideo', () => {
+  it('returns Error for unknown model', async () => {
+    const result = await generateVideo({
+      prompt: 'test',
+      model: 'nonexistent-model-xyz',
+    })
+    expect(result).toBeInstanceOf(Error)
+    expect((result as Error).message).toMatch(/Unknown model/)
+  })
+
+  it('returns Error when using image model as video model', async () => {
+    const result = await generateVideo({
+      prompt: 'test',
+      model: 'imagen-4.0-generate-001',
+    })
+    expect(result).toBeInstanceOf(Error)
+    expect((result as Error).message).toMatch(/not a video model/)
+  })
+
+  it('returns Error when reference-to-video mode has no reference images', async () => {
+    const result = await generateVideo({
+      prompt: 'test',
+      model: 'veo-3.1-fast-generate-001',
+      mode: 'reference-to-video',
+    })
+    expect(result).toBeInstanceOf(ValidationError)
+    expect((result as Error).message).toMatch(/referenceImages is required/)
+  })
+
+  it('returns Error when edit-video mode has no videoUrl', async () => {
+    const result = await generateVideo({
+      prompt: 'test',
+      model: 'grok-imagine-video',
+      mode: 'edit-video',
+      inputImage: new Uint8Array([1, 2, 3]),
+    })
+    expect(result).toBeInstanceOf(ValidationError)
+    expect((result as Error).message).toMatch(/videoUrl is required/)
+  })
+})
+
+describe('calculateCost', () => {
+  it('calculates per-image cost', () => {
+    const cost = calculateCost(
+      { type: 'per-image', perImage: 0.04 },
+      {},
+      3,
+    )
+    expect(cost).toBeCloseTo(0.12)
+  })
+
+  it('calculates per-token cost', () => {
+    const cost = calculateCost(
+      { type: 'per-token', inputPerM: 1.25, outputPerM: 5.0 },
+      { inputTokens: 1000, outputTokens: 500 },
+    )
+    // (1000 * 1.25 + 500 * 5.0) / 1_000_000 = 0.00375
+    expect(cost).toBeCloseTo(0.00375)
+  })
+
+  it('calculates per-video-second cost', () => {
+    const cost = calculateCost(
+      {
+        type: 'per-video-second',
+        defaultDurationSec: 5,
+        tiers: [{ costPerSecond: 0.05 }],
+      },
+      { durationSeconds: 10 },
+    )
+    expect(cost).toBeCloseTo(0.5)
+  })
+
+  it('uses default duration when none specified', () => {
+    const cost = calculateCost(
+      {
+        type: 'per-video-second',
+        defaultDurationSec: 5,
+        tiers: [{ costPerSecond: 0.05 }],
+      },
+      {},
+    )
+    expect(cost).toBeCloseTo(0.25)
+  })
+
+  it('returns null for unknown cost type', () => {
+    const cost = calculateCost({ type: 'unknown' }, {})
+    expect(cost).toBeNull()
+  })
+})
+
+describe('buildImageProviderOptions', () => {
+  it('builds google options with person generation', () => {
+    const opts = buildImageProviderOptions('google', {
+      allowPeople: true,
+      aspectRatio: '16:9',
+    })
+    expect(opts.google).toEqual({
+      personGeneration: 'allow_all',
+      aspectRatio: '16:9',
+    })
+  })
+
+  it('builds xai options with quality', () => {
+    const opts = buildImageProviderOptions('xai', {
+      allowPeople: false,
+      quality: 'high',
+      resolution: '4k',
+    })
+    expect(opts.xai).toEqual({
+      quality: 'high',
+      resolution: '4k',
+    })
+  })
+
+  it('returns empty for unknown provider', () => {
+    const opts = buildImageProviderOptions('unknown-provider', {
+      allowPeople: false,
+    })
+    expect(opts).toEqual({})
+  })
+})
+
+describe('buildVideoProviderOptions', () => {
+  it('builds xai edit-video options', () => {
+    const opts = buildVideoProviderOptions('xai', {
+      mode: 'edit-video',
+      videoUrl: 'https://example.com/video.mp4',
+      model: 'grok-imagine-video',
+    })
+    expect(opts?.xai).toEqual({
+      mode: 'edit-video',
+      videoUrl: 'https://example.com/video.mp4',
+    })
+  })
+
+  it('returns undefined for provider with no options', () => {
+    const opts = buildVideoProviderOptions('google', {
+      model: 'veo-3.1-fast-generate-001',
+    })
+    expect(opts).toBeUndefined()
+  })
+})