egaki 0.5.0 → 0.7.0

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}

@@ -2,12 +2,13 @@
 // Reads and writes API keys from ~/.config/egaki/credentials.json.
 // Keys are stored per-provider and injected as env vars at runtime.
 //
-// Most providers store a plain API key string. The 'chatgpt' provider stores
-// a structured ChatGptAuth object with OAuth tokens for the Codex backend flow.
+// Most providers store a plain API key string. OAuth providers store structured
+// token objects for their custom backend flows.
 import fs from 'node:fs'
 import path from 'node:path'
 import os from 'node:os'
 import type { ChatGptAuth } from './chatgpt-auth.js'
+import type { XaiAuth } from './xai-auth.js'
 
 export type ProviderInfo = {
   envVar: string
@@ -57,6 +58,37 @@ export const PROVIDERS: Record<string, ProviderInfo> = {
     label: 'fal.ai (Flux, SDXL, Recraft)',
     hint: 'Get your key at https://fal.ai/dashboard/keys',
   },
+  xai: {
+    envVar: 'XAI_API_KEY',
+    label: 'xAI (API key)',
+    hint: 'Get your key at https://console.x.ai/team/default/api-keys',
+  },
+  'xai-oauth': {
+    envVar: 'XAI_API_KEY',
+    label: 'xAI Grok Build (use your subscription)',
+    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'
@@ -72,8 +104,8 @@ function getCredentialsPath(): string {
   return path.join(getConfigDir(), 'credentials.json')
 }
 
-/** A credential value is either a plain API key string or a ChatGPT OAuth object. */
-export type CredentialValue = string | ChatGptAuth
+/** A credential value is a plain API key string, a ChatGPT OAuth object, or an xAI OAuth object. */
+export type CredentialValue = string | ChatGptAuth | XaiAuth
 export type Credentials = Record<string, CredentialValue>
 
 export function readCredentials(): Credentials {
@@ -115,6 +147,19 @@ export function getChatGptAuth(): ChatGptAuth | undefined {
   return undefined
 }
 
+export function saveXaiAuth(auth: XaiAuth): void {
+  const creds = readCredentials()
+  creds['xai-oauth'] = auth
+  writeCredentials(creds)
+}
+
+export function getXaiAuth(): XaiAuth | undefined {
+  const creds = readCredentials()
+  const val = creds['xai-oauth']
+  if (!val || typeof val !== 'object') return undefined
+  return val
+}
+
 export function removeProviderKey(provider: string): void {
   const creds = readCredentials()
   delete creds[provider]
@@ -127,17 +172,26 @@ export function getProviderKey(provider: string): string | undefined {
   return typeof val === 'string' ? val : undefined
 }
 
-// Inject all stored non-ChatGPT credentials as env vars so the AI SDK
+// Inject all stored non-OAuth credentials as env vars so the AI SDK
 // providers pick them up automatically. Env vars already set by the user take
 // precedence (we don't overwrite them).
+//
+// Special case: if xAI OAuth tokens exist, skip injecting the stored xai API
+// key so OAuth takes priority. Only an explicit XAI_API_KEY env var (set by
+// the user before egaki runs) will override OAuth.
 export function injectCredentialsToEnv(): void {
   const creds = readCredentials()
+  const hasXaiOAuth = Boolean(getXaiAuth())
   for (const [provider, value] of Object.entries(creds)) {
     const info = PROVIDERS[provider]
     if (!info) continue
 
-    // Skip ChatGPT OAuth entries — handled separately
+    // Skip OAuth entries — handled separately via custom fetch
     if (provider === 'chatgpt') continue
+    if (provider === 'xai-oauth') continue
+
+    // Skip stored xai key when OAuth tokens exist (OAuth takes priority)
+    if (provider === 'xai' && hasXaiOAuth && !process.env[info.envVar]) continue
 
     if (typeof value === 'string' && !process.env[info.envVar]) {
       process.env[info.envVar] = value
@@ -153,6 +207,16 @@ export function shouldUseChatGptBackend(): boolean {
   return !process.env['OPENAI_API_KEY'] && Boolean(getChatGptAuth())
 }
 
+/**
+ * Returns true when xAI models should use the OAuth flow instead of a direct
+ * XAI_API_KEY. Priority: explicit env var > xai-oauth tokens > stored xai key.
+ * Only an explicit XAI_API_KEY (set before egaki runs) overrides OAuth.
+ */
+export function shouldUseXaiOAuth(): boolean {
+  if (process.env['XAI_API_KEY']) return false
+  return Boolean(getXaiAuth())
+}
+
 // Check if a provider has a key available (from env or stored credentials).
 // Returns the source of the key for display purposes.
 export function getKeyStatus(provider: string): {
@@ -164,7 +228,7 @@ export function getKeyStatus(provider: string): {
     return { available: false, source: 'none' }
   }
 
-  // ChatGPT OAuth is a special case
+  // OAuth providers are special cases
   if (provider === 'chatgpt') {
     const auth = getChatGptAuth()
     if (auth) {
@@ -173,6 +237,25 @@ export function getKeyStatus(provider: string): {
     return { available: false, source: 'none' }
   }
 
+  if (provider === 'xai-oauth') {
+    const auth = getXaiAuth()
+    if (auth) {
+      return { available: true, source: 'oauth' }
+    }
+    return { available: false, source: 'none' }
+  }
+
+  // For xai provider, report the same priority used by generation:
+  // explicit env var > xai-oauth tokens > stored xai key.
+  if (provider === 'xai') {
+    if (process.env[info.envVar]) return { available: true, source: 'env' }
+    const oauthAuth = getXaiAuth()
+    if (oauthAuth) return { available: true, source: 'oauth' }
+    const stored = getProviderKey(provider)
+    if (stored) return { available: true, source: 'stored' }
+    return { available: false, source: 'none' }
+  }
+
   if (process.env[info.envVar]) {
     return { available: true, source: 'env' }
   }

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,
+      }
+    },
+  }
+}