# Animation File Format Version 2 - Encoding Specification

## File Structure

The file consists of three sections in order:

1. **Filename Block** (optional, for serial transmission)
2. **Header Block** (16 bytes)
3. **Frame Data Block** (variable size)

## Encoding Details

### 1. Filename Block
```
[filename_length: 2 bytes, uint16_t, little-endian]
[filename_bytes: N bytes, UTF-8 string]
```

### 2. Header Block (16 bytes total)
```
[0-3]    "ANIM" (4 bytes, ASCII)
[4-5]    frameCount (2 bytes, uint16_t, little-endian)
[6]      version (1 byte, uint8_t) = 2
[7]      frameRate (1 byte, uint8_t) = FPS
[8-15]   reserved (8 bytes, all zeros)
```

### 3. Frame Data Block
For each frame (0 to frameCount-1), all motors are stored in the same order:

```
For each frame:
  For each motor (in consistent order):
    [motor_id: 1 byte, uint8_t]
    [position: 2 bytes, uint16_t, little-endian, range 0-4095]
```

**Important**: 
- All frames contain the same motors in the same order
- Motor count = (Frame Data Block size) / (frameCount * 3)
- Each motor record is exactly 3 bytes: 1 byte ID + 2 bytes position

## Example File Layout

For a file with 100 frames and 20 motors:

```
[0-1]        Filename length (2 bytes)
[2-N]        Filename (N bytes)
[N+0-N+3]    "ANIM" (4 bytes)
[N+4-N+5]    100 (frameCount, 2 bytes)
[N+6]        2 (version, 1 byte)
[N+7]        24 (frameRate, 1 byte)
[N+8-N+15]   Reserved (8 bytes)
[N+16+]      Frame data:
              Frame 0: [motor0_id][motor0_pos][motor1_id][motor1_pos]...[motor19_id][motor19_pos]
              Frame 1: [motor0_id][motor0_pos][motor1_id][motor1_pos]...[motor19_id][motor19_pos]
              ...
              Frame 99: [motor0_id][motor0_pos][motor1_id][motor1_pos]...[motor19_id][motor19_pos]
```

Total frame data size = 100 frames × 20 motors × 3 bytes = 6,000 bytes