# VoiceLayer Complete Technical Reference (LLMs Full Specification)

VoiceLayer is a full-stack AI video production platform, headless video processing engine, and developer API built for creators, marketing agencies, and autonomous content pipelines.

## Architectural Overview

VoiceLayer operates as a multi-tier pipeline:
1. **Frontend Studio / UI**: Single-Page Web Application (`https://voicelayer.studio`) with client-side waveform analysis, video player preview, ASS subtitle positioning grid, and authentication via Supabase Auth.
2. **Serverless REST API**: Deployed on Vercel Edge/Serverless functions (`https://voicelayer.studio/api/*`) and Supabase Edge Functions.
3. **Async Render Worker Engine**: AWS Lambda with ffmpeg and libass for high-speed video clipping, silence removal, subtitle burning, and multi-track audio multiplexing.
4. **CloudFront CDN Asset Delivery**: All uploaded and generated assets are distributed globally via `https://assets.voicelayer.studio/` ensuring high throughput and sub-100ms video playback start times.

---

## Core Systems & Capabilities

### 1. AI Voice Cloning & WPS Duration Calibration Engine
- **Voice Clone Creation**: Accepts 3 audio recording samples (WAV or MP3, 10s–30s each) to train a neural voice embedding.
- **WPS (Words-Per-Second) Profiling**: Measures voice velocity (typically 2.2 to 3.4 WPS).
- **Zero-Waste Estimation**: Calculates `safe_duration_s = (word_count / WPS) * safety_margin`. This prevents overrunning video cutaways and eliminates blind audio generation charges.
- **Public URL**: `https://voicelayer.studio/ai-voice-cloning/`

### 2. AI Clip Finder & Video Repurposing Studio
- **Multimodal Video Understanding**: Ingests video content up to 2 hours in length. Identifies high-energy hooks, viral segments, humorous exchanges, and educational highlights.
- **Target Formats**: 9:16 vertical crop (1080x1920), 1:1 square, and 16:9 widescreen.
- **Auto-Subtitles**: Generates burned-in or ASS kinetic subtitles on the extracted clips.
- **Public URL**: `https://voicelayer.studio/ai-clip-finder/`

### 3. AI Auto-Editor (Smart Silence & Pause Remover)
- **Audio Noise Floor Detection**: Analyzes decibel amplitude across audio tracks with configurable threshold parameters (default `-40dB`).
- **Safety Padding Buffer**: Applies 100ms–250ms lead-in and lead-out margins around retained speech segments to preserve natural phonemes.
- **Lossless Jump Cuts**: Uses hardware-accelerated video cuts to render seamless talking-head videos with zero audio pops or visual glitches.
- **Public URL**: `https://voicelayer.studio/ai-auto-editor/`

### 4. AI Video Narration Agent
- **Scene-Aware Visual Parsing**: Extracts keyframes and interprets temporal transitions, identifying what is occurring on screen.
- **Script Synthesis**: Drafts natural, engaging voiceover copy synchronized to visual milestones.
- **Voice Assignment**: Associates distinct cloned or stock voices to different segments of the video timeline.
- **Public URL**: `https://voicelayer.studio/ai-narration-generator/`

### 5. Animated Subtitle & Kinetic Caption Engine
- **Supported Format**: Advanced SubStation Alpha (.ASS v4.00+).
- **Supported Effects**:
  - `karaoke`: Word-by-word active color transition.
  - `word_stack`: Cumulative multi-line kinetic reveal.
  - `word_by_word`: Single-word pop with scale animation.
  - `bounce`: Playful vertical spring animation.
  - `fade`: Smooth alpha blending between words.
  - `typewriter`: Character-by-character mechanical reveal.
- **Customization Options**:
  - Fonts: Inter, Roboto, Montserrat, Trebuchet MS, Arial Black, Comic Sans MS, and more.
  - Positioning: Explicit X/Y pixel coordinates with safe-zone margin guides for TikTok, YouTube Shorts, and Instagram Reels.
  - Colors: Primary text color, highlight effect color, outline/border width, and drop shadow blur.
- **Public URLs**:
  - `https://voicelayer.studio/ai-subtitle-generator/`
  - `https://voicelayer.studio/animated-captions-generator/`
  - `https://voicelayer.studio/tiktok-subtitle-generator/`
  - `https://voicelayer.studio/youtube-shorts-caption-generator/`
  - `https://voicelayer.studio/instagram-reels-subtitle-generator/`

---

## API Schemas & Reference

### Authentication Header
`X-API-Key: <your_api_key>`

### 1. Duration Estimation (`POST /api/estimate-durations`)
```json
{
  "voice_id": "string",
  "narrations": [
    {
      "text": "string"
    }
  ]
}
```

### 2. Video Compilation (`POST /api/compile`)
```json
{
  "video_url": "https://assets.voicelayer.studio/path/to/video.mp4",
  "mute_where_speech": "true",
  "narrations": [
    {
      "timestamp": "00:01.500",
      "text": "Hello world",
      "voice_id": "string",
      "font": "Inter",
      "effect": "karaoke",
      "text_color": "#FFFFFF",
      "effect_color": "#38BDF8",
      "aspect_ratio": "9:16",
      "subtitles": true,
      "x_position": 540,
      "y_position": 1400,
      "size": 1.0
    }
  ]
}
```

### 3. AI Auto-Editor (`POST /api/ai-auto-editor`)
```json
{
  "video_url": "https://assets.voicelayer.studio/path/to/video.mp4",
  "db_threshold": -40,
  "min_silence_duration": 0.4,
  "margin_buffer": 0.15
}
```

### 4. AI Clip Finder (`POST /api/ai-clip-finder`)
```json
{
  "video_url": "https://assets.voicelayer.studio/path/to/video.mp4",
  "prompt": "Extract high energy soundbites and viral hooks",
  "min_duration": 15,
  "max_duration": 60,
  "max_clips": 5
}
```

### 5. Check Job Status (`GET /api/jobs/:id`)
```json
{
  "job_id": "string",
  "status": "pending | processing | done | error",
  "progress": 85,
  "video_url": "https://assets.voicelayer.studio/rendered/video.mp4",
  "error": null
}
```

---

## Contact & Integration Support

- Primary Website: https://voicelayer.studio
- Company: PDV Automations (https://pdvautomations.com)
- Engineering Contact: polat@pdvautomations.com