# Tesla Light Show — User Guide

Tesla Light Show is the official open-source toolkit from Tesla Motors for creating custom synchronized light shows on Tesla vehicles. You design sequences in **xLights** (free, third-party sequencing software), export them as `.fseq` files, validate them with the included `validator.py` tool, and load the result onto a USB drive that the car reads.

---

## 1. Quick Start

**What you can do with this toolkit:**

- Control exterior lights, interior lighting, and closures (doors, frunk, trunk) in a fully custom animated sequence
- Create single-car or synchronized multi-car shows (examples include up to 8 cars)
- Validate `.fseq` files before loading — catch errors at your desk, not in the driveway
- Start immediately from seven pre-built example shows

**Prerequisites:** A supported Tesla vehicle, **xLights** (free download), Python 3.7+ _or_ a pre-compiled validator binary (Windows/macOS), a USB drive.

Validate an `.fseq` file:

```bash
python3 validator.py lightshow.fseq
```

```text
Found 240 frames, step time of 50 ms for a total duration of 0:00:12.
```

> [!TIP]
> Windows and macOS users can skip Python entirely — use the pre-compiled binaries `validator-windows.exe` and `validator-macos.zip` included at the repo root. Just double-click and drag-and-drop your file.

**Next steps:**
- Load one of the example shows — see Common Tasks
- Create your own show — see Core Usage
- Troubleshoot a validator error — see Troubleshooting

---

## 2. Installation

### System Requirements

| Component | Requirement |
|---|---|
| Tesla vehicle | Supported firmware with light show feature enabled |
| xLights | Third-party sequencing software (free, required for creating shows) |
| Python | 3.7 or later (required for `validator.py`; not needed for pre-built binaries) |
| USB drive | FAT32 formatted |

### Validator Setup

=== "Windows (pre-compiled)"
    Download `validator-windows.exe` from the repository root. No installation required — run it directly.

=== "macOS (pre-compiled)"
    Download `validator-macos.zip` from the repository root. Unzip, then run the extracted binary.

=== "Python (all platforms)"
    Python 3.7+ is required. No additional packages — `validator.py` uses only the standard library.

    ```bash
    python3 --version
    ```

    ```text
    Python 3.11.4
    ```

### Post-Install Verification

```bash
python3 validator.py examples/lightshow_example_3_The_Arrival_5_Car/"Car #1"/LightShow/lightshow.fseq
```

A valid file produces frame count and duration output. An invalid file produces a specific error message describing the violation.

> [!IMPORTANT]
> Always validate your `.fseq` file before loading it onto the USB drive. The vehicle will silently skip malformed files with no on-screen explanation.

---

## 3. Core Usage

### Step 1 — Get the xLights Show Folder

Tesla provides a pre-configured xLights project that maps all Tesla light channels correctly.

1. Download `xlights/tesla_xlights_show_folder.zip` from the repository.
2. Extract it to a local directory.
3. Open that directory as your xLights show folder.

> [!NOTE]
> For synchronized multi-car shows, use `xlights/tesla_xlights_cross_vehicle_folder.zip` instead. The cross-vehicle project has a different channel layout for coordinating multiple vehicles.

### Step 2 — Create Your Sequence in xLights

Design your light sequence using xLights' built-in effects. The Tesla show folder pre-configures all channel assignments so the correct lights respond to each channel.

### Step 3 — Export as FSEQ

Export your completed sequence as a `.fseq` file from xLights.

### Step 4 — Validate

```bash
python3 validator.py lightshow.fseq
```

The validator checks that the file meets Tesla's vehicle requirements:

| Check | Requirement |
|---|---|
| File format | FSEQ v2.0 (magic bytes `PSEQ`) |
| Channel count | Exactly **48** (standard vehicles) or **200** (Cybertruck) |
| Compression | V2 Uncompressed only |
| Step time | ≥ 15 ms |
| Total duration | ≤ 4 hours |
| FSEQ version | 2.0 or 2.2 (other versions: warning issued, not rejected) |

> [!WARNING]
> Your `.fseq` must be exported with exactly 48 or 200 channels. Model S, Model 3, Model X, and Model Y use 48 channels. Cybertruck uses 200 channels. Any other count fails validation.

### Step 5 — Load onto USB

1. Create a folder named `LightShow` at the root of a FAT32 USB drive.
2. Copy `lightshow.fseq` into `LightShow/`.
3. Optionally copy your audio file (`lightshow.mp3` or `lightshow.wav`) into `LightShow/`.

```text
USB root/
  LightShow/
    lightshow.fseq
    lightshow.mp3     (optional)
```

4. Insert the USB drive into your Tesla.
5. Start the show from the vehicle interface.

---

## 4. Common Tasks

### Try a Pre-Built Example Show

Seven complete examples are included in the `examples/` directory:

| Example | Cars | Audio |
|---|---|---|
| `lightshow_example_1_elevator_music.zip` | 1 | — |
| `lightshow_example_2_Max_Carlisle_Auld_Lang_Syne_In_the_City.zip` | 1 | — |
| `lightshow_example_3_The_Arrival_5_Car/` | 5 | MP3 |
| `lightshow_example_4_Ready_for_Assault_8_Car/` | 8 | WAV |
| `lightshow_example_5_Cyber_Symphony_4_Car/` | 4 | WAV |
| `lightshow_example_6_Ready_for_Assault_1_Car.zip` | 1 | — |
| `lightshow_example_7_Cyber_Symphony_1_Car.zip` | 1 | — |

**To try example 1:**
1. Extract `examples/lightshow_example_1_elevator_music.zip`.
2. Validate the extracted `.fseq` file with the validator.
3. Copy to USB as described in Core Usage Step 5.

### Run a Multi-Car Synchronized Show

Multi-car shows provide a separate sequence for each vehicle. Each car gets its own USB drive.

Using example 3 (5-car):

1. Open `examples/lightshow_example_3_The_Arrival_5_Car/`.
2. For each participating car, copy that car's `LightShow/` contents to a separate USB drive:
   - Car #1's USB: contents of `Car #1/LightShow/` → `LightShow/` on USB
   - Car #2's USB: contents of `Car #2/LightShow/` → `LightShow/` on USB
   - (repeat for each car)
3. Validate each car's `lightshow.fseq` before loading.
4. Insert USB drives into all cars simultaneously.
5. Trigger all shows at the same moment.

> [!NOTE]
> Examples 4 and 5 use WAV audio; example 3 uses MP3. Both formats are confirmed as working by the included example files.

### Validate Without Python

**Windows:**

1. Run `validator-windows.exe` (double-click or terminal).
2. When prompted, drag-and-drop your `.fseq` file into the window.

**macOS:**

1. Unzip `validator-macos.zip`.
2. Run the extracted binary.
3. Drag-and-drop your `.fseq` file when prompted.

### Create a Cross-Vehicle Show

1. Extract `xlights/tesla_xlights_cross_vehicle_folder.zip`.
2. Read `cross-vehicle-shows/README.md` for car positioning and channel layout details.
3. Design your sequence using the cross-vehicle channel assignments.
4. Export and validate each car's `.fseq` file individually.

---

## 5. Troubleshooting

**Quick diagnostic:** Run `validator.py` on the file first. All validator errors are specific and self-describing.

### Error: `Unknown file format, expected FSEQ v2.0`

**Cause:** The `.fseq` file is not a valid FSEQ v2 file. Common causes: wrong export format in xLights, file corruption, or exporting from the wrong project.

**Solution:**
1. Re-open the sequence in xLights.
2. Confirm you are exporting to FSEQ format (not a different output type).
3. Re-export and re-validate.
4. If the error persists, try downloading an older xLights release from https://github.com/smeighan/xLights/releases

**Prevention:** Use the official Tesla xLights show folder as your project base.

> [!WARNING]
> Community issue #67 documented this error when newer xLights versions defaulted to FSEQ v2.2. The validator now accepts v2.2 with a warning rather than an error — if you see this error, the problem is not version 2.2 but a more fundamental format mismatch.

### Error: `Expected 48 or 200 channels, got {N}`

**Cause:** The exported file has the wrong channel count. The xLights project is not using Tesla's layout, or the wrong show folder was opened.

**Solution:**
1. Reopen the xLights project.
2. Confirm you opened the Tesla show folder from `xlights/tesla_xlights_show_folder.zip`, not a custom layout.
3. Re-export and re-validate.

**Prevention:** Always start from the official Tesla show folder project. (GitHub issue #85)

### Error: `Expected file format to be V2 Uncompressed`

**Cause:** The `.fseq` file uses FSEQ compression. Tesla vehicles require uncompressed V2 format.

**Solution:**
1. In xLights, locate the output/export compression settings.
2. Set compression to None (uncompressed).
3. Re-export the `.fseq` file and re-validate.

**Prevention:** The Tesla show folder project should have compression disabled by default.

### Error: `Expected total duration to be less than 4 hours, got {duration}`

**Cause:** The sequence exceeds 4 hours total length. Almost always a configuration error — check that the step time and frame count are set correctly in xLights.

**Solution:**
1. Review the sequence length and step time in xLights.
2. Verify step time is at least 15 ms.
3. Confirm the total frame count matches the intended duration.

### WARNING: FSEQ Version Message

**Cause:** Your xLights export produced a FSEQ version other than 2.0 or 2.2. This is a warning, not a failure — the file passed validation.

```text
WARNING: FSEQ version is 2.3. Only version 2.0 and 2.2 have been validated.
If the car fails to read this file, download an older version of XLights at https://github.com/smeighan/xLights/releases
```

**Solution:** Test on the vehicle. If the car does not read the file, download an older xLights release that produces v2.0.

> [!WARNING]
> A version warning does not guarantee vehicle compatibility. Always test after seeing this message.

### Example 3 (5-Car) Fails on Model Y

**Cause:** Pre-built multi-car examples may have been authored for specific vehicle configurations. (GitHub issue #84)

**Solution:**
1. Validate the specific car's `.fseq` file with the validator.
2. Confirm the channel count matches your vehicle (48 for standard, 200 for Cybertruck).
3. Confirm you are using the correct car number's files for each vehicle.

---

## 6. FAQ

**Q: Which Tesla vehicles support custom light shows?**

The validator accepts 48-channel files (Model S, Model 3, Model X, Model Y) and 200-channel files (Cybertruck). Light show support requires compatible vehicle firmware — check your vehicle's release notes for confirmation.

**Q: Do I need to buy xLights?**

No. xLights is free and open-source. Tesla provides the pre-configured show folder to map channels correctly.

**Q: Which audio formats does the car accept?**

The included examples use both MP3 (example 3) and WAV (examples 4 and 5). Both are confirmed working by the example files.

**Q: Can I have multiple shows on one USB drive?**

The car reads a `LightShow/` folder at the USB root. For multiple shows, consult your vehicle's documentation on how to select among multiple stored shows.

**Q: Why does the validator warn about FSEQ version but not fail?**

FSEQ versions 2.0 and 2.2 are the only versions confirmed to work with Tesla vehicles. Version 2.2 was validated by the community. Other versions issue a warning so you can still test them rather than being blocked outright.

**Q: The validator used to reject 200-channel files — is that fixed?**

Yes. An older version of the validator required exactly 48 channels. The current `validator.py` accepts either 48 (standard vehicles) or 200 (Cybertruck). (GitHub issue #85)

**Q: How long can a light show be?**

Up to 4 hours, with a minimum step time of 15 ms. Practical shows are typically a few minutes.

**Q: Can I share my show with other Tesla owners?**

Yes — distribute your `.fseq` and audio files directly. Other creators can also share the xLights `.xsq` project file (included in examples 3, 4, 5) for remixing.

**Q: Can I add new light channels beyond the current 48/200?**

Not with the current validator or xLights project. This is an open feature request (GitHub issue #141) that would require changes to both the validator and the xLights channel layout.

---

_Generated May 2026 from teslamotors/light-show at 9f94951. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._