voicebox/docs/api/recordings.mdx

---
title: "Recordings API"
description: "Record and transcribe audio"
---

## Start Recording

```http
POST /recordings/start
```

**Request:**
```json
{
  "source": "microphone"
}
```

**Response:**
```json
{
  "recording_id": "rec123",
  "status": "recording"
}
```

## Stop Recording

```http
POST /recordings/stop
```

**Request:**
```json
{
  "recording_id": "rec123"
}
```

**Response:**
```json
{
  "recording_id": "rec123",
  "audio_url": "/audio/rec123.wav",
  "duration": 15.5
}
```

## Transcribe Audio

```http
POST /transcribe
```

**Request:** (multipart/form-data)
```
audio: <file>
language: "en" (optional)
```

**Response:**
```json
{
  "text": "Transcribed speech text here",
  "language": "en",
  "duration": 15.5,
  "confidence": 0.95
}
```

## TypeScript Example

```typescript
import { VoiceboxClient } from '@/lib/api'

const client = new VoiceboxClient({
  baseUrl: 'http://localhost:17493'
})

// Start recording
const recording = await client.startRecording({
  source: 'microphone'
})

// ... record audio ...

// Stop recording
const result = await client.stopRecording(recording.id)

// Transcribe
const transcription = await client.transcribe(audioFile, 'en')
console.log(transcription.text)
```

For full API documentation, visit `http://localhost:17493/docs` when the server is running.