Neural Documentation

curl -X GET "https://narrator.corrin.ai/api/v1/tts/voices" \
  -H "x-api-key: YOUR_API_KEY"

import requests

url = "https://narrator.corrin.ai/api/v1/tts/synthesize"

payload = {
    "text": "Welcome to the future of audio narration.",
    "voice": "Chronicler",
    "temperature": 0.8
}

headers = {
    "x-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

# Save audio file (WAV format, 24kHz, PCM Float32)
with open("speech.wav", "wb") as f:
    f.write(response.content)

// Connect to WebSocket with voice and API key
const ws = new WebSocket(
  'wss://narrator.corrin.ai/api/v1/tts/stream?voice=Chronicler&api_key=YOUR_API_KEY'
);

const audioContext = new AudioContext();
let scheduledTime = 0;

ws.onmessage = async (event) => {
  const msg = JSON.parse(event.data);

  if (msg.status === 'ready') {
    // Connection ready - send text to synthesize
    ws.send("Hello! This is real-time streaming synthesis.");

  } else if (msg.type === 'audio') {
    // Decode base64 to raw bytes
    const audioBytes = Uint8Array.from(atob(msg.data), c => c.charCodeAt(0));
    const audioFloat32 = new Float32Array(audioBytes.buffer);

    // Create AudioBuffer for playback
    const audioBuffer = audioContext.createBuffer(1, audioFloat32.length, msg.sample_rate);
    audioBuffer.getChannelData(0).set(audioFloat32);

    // Schedule for seamless playback
    const source = audioContext.createBufferSource();
    source.buffer = audioBuffer;
    source.connect(audioContext.destination);
    source.start(audioContext.currentTime + scheduledTime);
    scheduledTime += audioBuffer.duration;

  } else if (msg.type === 'finalComplete') {
    console.log('Synthesis complete!');
    scheduledTime = 0; // Reset for next request
  }
};

const ws = new WebSocket(
  'wss://narrator.corrin.ai/api/v1/tts/script/stream?api_key=YOUR_API_KEY'
);

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);

  if (msg.status === 'ready') {
    // Send script with character-voice mappings
    ws.send(JSON.stringify({
      "content": `[NARRATOR] Once upon a time, in a distant land...
[PRINCESS] "I wish for adventure," she sighed.
[NARRATOR] said the princess.
[KNIGHT] "Then adventure you shall have!"
[NARRATOR] replied the brave knight.`,
      "voices": {
        "NARRATOR": "Chronicler",
        "PRINCESS": "Serenity",
        "KNIGHT": "Thundervox"
      },
      "default_voice": "Chronicler",
      "filename": "chapter1"
    }));

  } else if (msg.type === 'audio') {
    console.log(`Audio from ${msg.character} (${msg.section}/${msg.total_sections})`);
    playAudioChunk(msg.data, msg.sample_rate);

  } else if (msg.type === 'sectionComplete') {
    console.log(`Completed: ${msg.character}`);

  } else if (msg.type === 'finalComplete') {
    console.log('All narration complete!');
  }
};

const ws = new WebSocket(
  'wss://narrator.corrin.ai/api/v1/stt/stream?api_key=YOUR_API_KEY'
);

function encodePcmBase64(pcm /* Float32Array */) {
  const bytes = new Uint8Array(pcm.buffer, pcm.byteOffset, pcm.byteLength);
  let binary = '';
  for (let i = 0; i < bytes.length; i++) binary += String.fromCharCode(bytes[i]);
  return btoa(binary);
}

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);

  if (msg.status === 'ready') {
    // sample_rate is 24000 — start sending ~80ms frames
    ws.send(JSON.stringify({
      type: 'audio',
      data: encodePcmBase64(pcmFrame)
    }));

  } else if (msg.type === 'word') {
    console.log(msg.text, msg.start_time); // live insert into the editor

  } else if (msg.type === 'finalComplete') {
    console.log('Transcript:', msg.text);
  }
};

// When the user stops recording:
// ws.send(JSON.stringify({ type: 'stop' }));

# Install: python -m pip install websockets
# Set NARRATOR_API_KEY, then run: python transcribe.py speech.wav
# Input: mono, 24,000 Hz, 16-bit PCM WAV.
import asyncio, base64, json, os, struct, sys, wave
from urllib.parse import urlencode
import websockets

async def transcribe(path):
    query = urlencode({"api_key": os.environ["NARRATOR_API_KEY"]})
    url = "wss://narrator.corrin.ai/api/v1/stt/stream?" + query
    with wave.open(path, "rb") as audio:
        assert (audio.getnchannels(), audio.getframerate(), audio.getsampwidth()) == (1, 24000, 2)
        async with websockets.connect(url, open_timeout=30) as ws:
            ready = json.loads(await asyncio.wait_for(ws.recv(), timeout=300))
            if ready.get("status") != "ready":
                raise RuntimeError(ready.get("error", "ASR is not ready"))

            async def send_audio():
                while raw := audio.readframes(1920):
                    samples = [s[0] / 32768.0 for s in struct.iter_unpack("<h", raw)]
                    pcm = struct.pack("<" + "f" * len(samples), *samples)
                    await ws.send(json.dumps({"type": "audio", "data": base64.b64encode(pcm).decode()}))
                    await asyncio.sleep(len(samples) / 24000)
                await ws.send(json.dumps({"type": "stop"}))

            sender = asyncio.create_task(send_audio())
            try:
                while True:
                    msg = json.loads(await asyncio.wait_for(ws.recv(), timeout=60))
                    if msg.get("status") == "error":
                        raise RuntimeError(msg["error"])
                    if msg.get("type") == "word":
                        print(msg["text"], end=" ", flush=True)
                    if msg.get("type") == "finalComplete":
                        print("\nTranscript:", msg["text"])
                        break
                await sender
            finally:
                sender.cancel()
                await asyncio.gather(sender, return_exceptions=True)

asyncio.run(transcribe(sys.argv[1]))

import requests

url = "https://narrator.corrin.ai/api/v1/script/format-json"

payload = {
    "text": """Once upon a time, there was a princess.
"I would like a cup of coffee," said the princess.
"I'll have the same," replied the prince with a smile.""",
    "model": "gpt-4o-mini"
}

headers = {
    "x-api-key": "YOUR_API_KEY",
    "x-openrouter-api-key": "sk-or-v1-xxxxxxxxxxxxx",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)
result = response.json()

# Use the formatted script
print(result["formatted_text"])
# Output:
# [NARRATOR] Once upon a time, there was a princess.
# [PRINCESS] "I would like a cup of coffee,"
# [NARRATOR] said the princess.
# [PRINCE] "I'll have the same,"
# [NARRATOR] replied the prince with a smile.

import requests
import asyncio
import websockets
import json
import base64

BASE_URL = "https://narrator.corrin.ai/api/v1"
API_KEY = "YOUR_API_KEY"
OPENROUTER_KEY = "sk-or-v1-xxxxxxxxxxxxx"

headers = {
    "x-api-key": API_KEY,
    "x-openrouter-api-key": OPENROUTER_KEY,
}

# Step 1: Read a Markdown note or plain-text file
with open("story.md", encoding="utf-8") as f:
    note_text = f.read()

# Step 2: Format as script with character detection
script_resp = requests.post(
    f"{BASE_URL}/script/format-json",
    json={"text": note_text, "model": "gpt-4o-mini"},
    headers={**headers, "Content-Type": "application/json"}
)
script_data = script_resp.json()
formatted_script = script_data["formatted_text"]
characters = script_data["script"]["characters"]

print(f"Detected characters: {characters}")

# Step 3: Create voice mapping for each character
voice_mapping = {
    "NARRATOR": "Chronicler",
    "PRINCESS": "Serenity",
    "PRINCE": "Thundervox",
    "WITCH": "Mysterion",
}

# Step 4: Stream multi-character narration
async def stream_narration():
    uri = f"wss://narrator.corrin.ai/api/v1/tts/script/stream?api_key={API_KEY}"
    audio_chunks = []

    async with websockets.connect(uri) as ws:
        # Wait for ready
        ready = json.loads(await ws.recv())
        print(f"Connected: {ready}")

        # Send script with voice mappings
        await ws.send(json.dumps({
            "content": formatted_script,
            "voices": voice_mapping,
            "default_voice": "Chronicler",
            "filename": "my_story"
        }))

        # Collect audio chunks
        while True:
            msg = json.loads(await ws.recv())

            if msg["type"] == "audio":
                audio_chunks.append(base64.b64decode(msg["data"]))
                print(f"  {msg['character']} ({msg['section']}/{msg['total_sections']})")

            elif msg["type"] == "finalComplete":
                print(f"Complete! {msg['total_sections']} sections")
                break

    # Save combined audio (would need WAV header in production)
    with open("narration.raw", "wb") as f:
        f.write(b"".join(audio_chunks))

    print("Saved narration.raw")

asyncio.run(stream_narration())

# Install FastRTC with voice activity detection
pip install "fastrtc[vad]"

# Additional dependencies for this example
pip install websockets numpy

import asyncio
import json
import base64
import numpy as np
import websockets
from fastapi import FastAPI
from fastrtc import ReplyOnPause, Stream

API_KEY = "YOUR_API_KEY"
NARRATOR_WS_URL = "wss://narrator.corrin.ai/api/v1/tts/stream"

async def synthesize_with_narrator(text: str, voice: str = "Chronicler"):
    """Stream TTS audio from Narrator API."""
    uri = f"{NARRATOR_WS_URL}?voice={voice}&api_key={API_KEY}"

    async with websockets.connect(uri) as ws:
        # Wait for ready signal
        ready = json.loads(await ws.recv())
        if ready.get("status") != "ready":
            return

        # Send text for synthesis
        await ws.send(text)

        # Receive and yield audio chunks
        while True:
            msg = json.loads(await ws.recv())

            if msg.get("type") == "audio":
                # Decode base64 audio to numpy array
                audio_bytes = base64.b64decode(msg["data"])
                audio_array = np.frombuffer(audio_bytes, dtype=np.float32)
                sample_rate = msg.get("sample_rate", 24000)
                yield (sample_rate, audio_array)

            elif msg.get("type") == "finalComplete":
                break

def voice_assistant(audio: tuple[int, np.ndarray]):
    """
    Handler triggered when user stops speaking.
    Receives audio, processes it, and yields TTS response.
    """
    sample_rate, audio_array = audio

    # Step 1: Transcribe user audio with Narrator /api/v1/stt/stream
    # user_text = transcribe(audio_array, sample_rate)
    user_text = "Hello, tell me about the weather."  # Placeholder

    # Step 2: Generate response (use your preferred LLM)
    # response_text = generate_response(user_text)
    response_text = "The weather today is sunny with a high of 72 degrees."

    # Step 3: Stream TTS response from Narrator API
    async def stream_response():
        async for chunk in synthesize_with_narrator(response_text):
            yield chunk

    # Run async generator in sync context
    loop = asyncio.new_event_loop()
    gen = stream_response()
    try:
        while True:
            yield loop.run_until_complete(gen.__anext__())
    except StopAsyncIteration:
        pass
    finally:
        loop.close()

# Create the FastRTC stream
stream = Stream(
    handler=ReplyOnPause(voice_assistant),
    modality="audio",
    mode="send-receive",
)

# Mount on FastAPI
app = FastAPI()
stream.mount(app)

# Run with: uvicorn voice_assistant:app --host 0.0.0.0 --port 8000
# Test with: stream.ui.launch() for built-in UI