# Tesla Light Show Generator — How-To Guide

Convert any song into a fully choreographed Tesla light show `.fseq` file using AI-powered audio analysis. No xLights, no manual timeline editing — just a song file and a prompt.

---

## How It Works

The pipeline has three stages:

1. **Audio Analysis** — Extracts beats, tempo, drops, stereo field, harmonic content, and song structure from your WAV file using `librosa` (Python audio library)
2. **Show Composition** — Maps every musical event to specific Tesla light channels: kick drum → headlights, snare → signature lights, hi-hats → side markers, drops → trunk open + mirror flap + charge port dance, etc.
3. **FSEQ Generation** — Writes a Tesla-compatible `.fseq` v2.0 binary file at 50 FPS (20ms steps) with 48 channels

---

## Prerequisites

Everything is already set up on this machine. For reference, here's what's installed:

| Tool | Location |
|------|----------|
| Python | `C:\Python314\python.exe` |
| Skill scripts | `C:\Users\Gaming PC\.claude\skills\tesla-light-show\scripts\` |
| ffmpeg (MP3→WAV) | `C:\Users\Gaming PC\AppData\Local\Microsoft\WinGet\Packages\Gyan.FFmpeg_...\bin\ffmpeg.exe` |
| Tesla Validator | `C:\Users\Gaming PC\Downloads\light-show\validator.py` |

**Python packages required:**
```
pip install numpy librosa scipy
```

---

## Full Pipeline

### Step 1 — Get a WAV File

Tesla requires **44.1 kHz stereo WAV**. If you have an MP3, convert it first:

```powershell
& "C:\Users\Gaming PC\AppData\Local\Microsoft\WinGet\Packages\Gyan.FFmpeg_Microsoft.Winget.Source_8wekyb3d8bbwe\ffmpeg-8.1.1-full_build\bin\ffmpeg.exe" `
    -i "C:\path\to\song.mp3" `
    -ar 44100 -ac 2 `
    "C:\path\to\song.wav"
```

### Step 2 — Analyze the Audio

```powershell
cd "C:\Users\Gaming PC\.claude\skills\tesla-light-show\scripts"

python analyze_audio.py `
    "C:\path\to\song.wav" `
    "C:\path\to\song_analysis.json"
```

**Output:** A JSON file with ~30 audio features per 20ms frame including beats, BPM, drops, stereo panning, harmonic content, and detected song sections (intro/verse/chorus/bridge/outro).

**Sample output:**
```
Analyzed song.wav: 178.1s, 8905 frames, tempo ≈ 130.4 BPM, meter 4/4,
342 beats (87% tracker agreement), 86 downbeats, 1,204 onsets,
0 drops, stereo_width≈0.41, analyzers=librosa
  structure: intro(18s) + verse(42s) + chorus(38s) + verse(28s) + chorus(38s) + outro(14s)
```

### Step 3 — Compose the Light Show

```powershell
python compose_show.py `
    --analysis "C:\path\to\song_analysis.json" `
    --model model_3 `
    --out "C:\path\to\song.fseq"
```

**Supported models:**
| Flag | Vehicle |
|------|---------|
| `model_3` | Model 3 (pre-2024) |
| `model_3_highland` | Model 3 (2024+ Highland refresh) |
| `model_s` | Model S |
| `model_x` | Model X |
| `model_y` | Model Y |
| `cybertruck` | Cybertruck |

**Output:** A `.fseq` file matching your WAV file's exact duration.

### Step 4 — Validate

```powershell
echo "" | python "C:\Users\Gaming PC\Downloads\light-show\validator.py" "C:\path\to\song.fseq"
```

A passing show prints `✓ FSEQ file is valid` with frame/channel/duration stats.

### Step 5 — Load Onto Your Tesla

1. Format a USB drive as **FAT32**
2. Create a folder called exactly `LightShow` at the root
3. Copy both files into `LightShow\`:
   - `song.fseq`  ← rename to `lightshow.fseq`
   - `song.wav`   ← rename to `lightshow.wav`
4. Plug USB into your Tesla's media port
5. On the car: **Entertainment → Light Show**

> **Important:** The files must be named exactly `lightshow.fseq` and `lightshow.wav` — Tesla won't recognize other filenames.

---

## What Gets Choreographed

The composer intelligently maps musical features to car hardware:

| Musical Feature | Car Hardware |
|----------------|--------------|
| Kick drum / bass hit | Headlights (outer + inner beams) flash |
| Snare / mid-frequency hit | Signature lights + fog lights flash |
| Hi-hats / high frequency | Side markers + side repeaters sparkle |
| Strong beat (downbeat) | All front lights + brake + tail flash |
| Stereo pan (left/right) | Corresponding side of car lights |
| Drop / energy surge | Full front blast + rear lights |
| Song climax (highest energy chorus) | Trunk opens → dances → closes, mirrors flap, charge port dances |
| Stereo mix opens wide | Front fogs + aux park wash |
| Outro drum roll | Full strobe across all lights |
| Silence / applause | Car stays completely dark |

### Narrative Arc

The show builds automatically based on song structure:

- **Intro:** Sparse — one beam alternates left/right every 4th beat, soft ramps
- **Build (verses):** Every 2nd beat, turn signal blinkers start, side markers sparkle on hi-hats
- **Climax (chorus):** Every beat hit, full front/rear lighting, left/right alternating at full intensity
- **Outro:** Settling down, breathing ramps, final strobe if the outro is energetic

---

## Tips

**For the best results:**
- Use a **studio recording** (not a live version) — clean audio = tighter beat detection
- Songs with **clear kick/snare patterns** produce the most satisfying shows
- **4/4 time signature** songs work best; the composer handles 3/4 but prefers 4/4
- Songs **2-5 minutes** are ideal for Tesla — the car may time out on very long files

**BPM sweet spot:** 100–140 BPM gives the most energetic shows. Very slow songs (<70 BPM) produce slow breathing ramps; very fast songs (>160 BPM) may clip some effects.

**Multiple songs:** Each song needs its own analysis + compose run. The USB can only hold one show at a time (one `lightshow.fseq` + one `lightshow.wav`).

---

## Troubleshooting

| Problem | Fix |
|---------|-----|
| `ValueError: Unsupported sample width` | Re-convert WAV with ffmpeg using `-ar 44100 -ac 2` |
| Validator fails: "too many frames" | Song may be too long. Try trimming to under 5 min |
| Show plays but lights don't sync | Ensure WAV is 44100 Hz — check with `ffprobe song.wav` |
| Car doesn't see the show | File must be named `lightshow.fseq` and `lightshow.wav` exactly, inside `LightShow\` folder on FAT32 |
| Beat detection feels off | Try a different version of the song (different master/mix) |
| `librosa not found` | Run `pip install librosa` |

---

## Prompts for Claude

Copy-paste any of these prompts to generate a light show in a new Claude session.

---

### 🎵 All-In-One: MP3 to Light Show

```
I want to convert an MP3 file to a Tesla light show.

MP3 file path: "C:\path\to\song.mp3"
Tesla model: Model 3 (pre-2024)
Output folder: C:\Users\Gaming PC\Downloads\

Please:
1. Convert the MP3 to a 44.1kHz stereo WAV using ffmpeg
2. Run analyze_audio.py on the WAV to generate the analysis JSON
3. Run compose_show.py to generate the .fseq file
4. Validate the output with the Tesla validator
5. Tell me the final file locations and stats (duration, BPM, channel count)

Skill scripts are at: C:\Users\Gaming PC\.claude\skills\tesla-light-show\scripts\
ffmpeg is at: C:\Users\Gaming PC\AppData\Local\Microsoft\WinGet\Packages\Gyan.FFmpeg_Microsoft.Winget.Source_8wekyb3d8bbwe\ffmpeg-8.1.1-full_build\bin\ffmpeg.exe
Tesla validator is at: C:\Users\Gaming PC\Downloads\light-show\validator.py
```

---

### 🎵 WAV File (Already Have It)

```
I want to generate a Tesla light show from a WAV file.

WAV file path: "C:\path\to\song.wav"
Tesla model: Model 3 (pre-2024)
Output folder: C:\Users\Gaming PC\Downloads\

Please:
1. Run analyze_audio.py to generate the analysis JSON
2. Run compose_show.py to generate the .fseq file
3. Validate with the Tesla validator
4. Give me the final file locations and show stats

Skill scripts are at: C:\Users\Gaming PC\.claude\skills\tesla-light-show\scripts\
Tesla validator is at: C:\Users\Gaming PC\Downloads\light-show\validator.py
```

---

### 🚗 Different Tesla Model

Just change the model name in any prompt above. Valid values:
- `Model 3 (pre-2024)` → `model_3`
- `Model 3 Highland (2024+)` → `model_3_highland`
- `Model S` → `model_s`
- `Model X` → `model_x`
- `Model Y` → `model_y`
- `Cybertruck` → `cybertruck`

---

### 🔁 Batch: Multiple Songs at Once

```
I want to convert multiple songs to Tesla light shows.

Tesla model: Model 3 (pre-2024)
Output folder: C:\Users\Gaming PC\Downloads\LightShows\

Songs to process:
1. "C:\path\to\song1.mp3"
2. "C:\path\to\song2.wav"
3. "C:\path\to\song3.mp3"

For each song:
- Convert MP3s to WAV (44.1kHz stereo) if needed
- Run analyze_audio.py
- Run compose_show.py
- Validate and report stats

Name output files after the song (e.g. song1.fseq, song1.wav).

Skill scripts: C:\Users\Gaming PC\.claude\skills\tesla-light-show\scripts\
ffmpeg: C:\Users\Gaming PC\AppData\Local\Microsoft\WinGet\Packages\Gyan.FFmpeg_Microsoft.Winget.Source_8wekyb3d8bbwe\ffmpeg-8.1.1-full_build\bin\ffmpeg.exe
Validator: C:\Users\Gaming PC\Downloads\light-show\validator.py
```

---

## Files on This Machine

| File | Purpose |
|------|---------|
| `analyze_audio.py` | Audio feature extraction — beats, BPM, sections, stereo field |
| `compose_show.py` | Maps audio features → Tesla light channels, writes FSEQ |
| `fseq_writer.py` | Low-level FSEQ v2.0 binary format writer |
| `validator.py` | Verifies the FSEQ file passes Tesla's format checks |

---

## Example Shows Already Generated

| Song | Duration | BPM | Output Files |
|------|----------|-----|-------------|
| noname.mp3 | 2:58 | 130.4 | `C:\Users\Gaming PC\Downloads\noname.fseq` + `noname.wav` |
| IShowSpeed - World Cup | 4:58 | 125 | `C:\Users\Gaming PC\Downloads\ishowspeed_worldcup.fseq` + `ishowspeed_worldcup.wav` |

Both validated ✅ for Model 3 (pre-2024), 48 channels.

---

*Built with Claude · Tesla Light Show Skill · `analyze_audio.py` + `compose_show.py` + `fseq_writer.py`*