From 392a4cac6fbf088b15077bb45df5a3c8debfa069 Mon Sep 17 00:00:00 2001
From: shodan <mega@ioexception.at>
Date: Sat, 3 Oct 2026 22:56:18 +0200
Subject: [PATCH 01/21] feat(http): stream WAV audio to the speaker with POST
 /play

The request body is parsed as it arrives and written straight to I2S, so a
clip of any length plays with about 1.5 KB of buffering. I2S backpressure
paces the upload to real time; animation, eyes and LED keep updating between
speaker writes because loop() is blocked while the body streams.

Accepts 16-bit mono PCM at SAMPLE_RATE and answers 415 with the reason
otherwise. Auth and Wi-Fi checks run before any audio plays.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 platformio.ini                           |   1 +
 src/audio/audio.cpp                      |  33 ++++
 src/audio/audio.h                        |   2 +
 src/audio/wav_parser.cpp                 | 237 +++++++++++++++++++++++
 src/audio/wav_parser.h                   |  73 +++++++
 src/audio/wav_stream.cpp                 |  41 +---
 src/http/json.cpp                        |  16 +-
 src/http/json.h                          |   2 +
 src/http/play_handlers.cpp               | 118 +++++++++++
 src/http/play_handlers.h                 |   8 +
 src/http/routes.cpp                      |   7 +
 src/http/settings_handlers.cpp           |   2 +-
 test/test_wav_parser/test_wav_parser.cpp | 208 ++++++++++++++++++++
 13 files changed, 701 insertions(+), 47 deletions(-)
 create mode 100644 src/audio/wav_parser.cpp
 create mode 100644 src/audio/wav_parser.h
 create mode 100644 src/http/play_handlers.cpp
 create mode 100644 src/http/play_handlers.h
 create mode 100644 test/test_wav_parser/test_wav_parser.cpp

diff --git a/platformio.ini b/platformio.ini
index 47dad924..f950b4a7 100644
--- a/platformio.ini
+++ b/platformio.ini
@@ -51,6 +51,7 @@ build_src_filter =
     -<**/*.*>
     +<settings/validate.cpp>
     +<display/eyes/styles/eye_style_ids.cpp>
+    +<audio/wav_parser.cpp>
 build_flags = -std=c++17 -Iinclude -Isrc
 
 ; Opt-in OLED-only application. Building does not upload or change robot settings.
diff --git a/src/audio/audio.cpp b/src/audio/audio.cpp
index 33b8163e..bc49a271 100644
--- a/src/audio/audio.cpp
+++ b/src/audio/audio.cpp
@@ -96,6 +96,39 @@ bool initAudioStorage() {
   return true;
 }
 
+void writeMonoToSpeaker(const int16_t* samples, size_t count) {
+  constexpr size_t FRAMES = 256;
+
+  int16_t buffer[FRAMES * 2];
+
+  const uint8_t volume = settingsVolume();
+
+  while (count > 0) {
+    const size_t framesThisTime = count < FRAMES ? count : FRAMES;
+
+    for (size_t i = 0; i < framesThisTime; i++) {
+      int32_t scaled = (static_cast<int32_t>(samples[i]) * volume) / 100;
+
+      if (scaled > 32767) {
+        scaled = 32767;
+      } else if (scaled < -32768) {
+        scaled = -32768;
+      }
+
+      buffer[i * 2] = static_cast<int16_t>(scaled);
+      buffer[i * 2 + 1] = static_cast<int16_t>(scaled);
+    }
+
+    I2S.write(
+      reinterpret_cast<uint8_t*>(buffer),
+      framesThisTime * 2 * sizeof(int16_t)
+    );
+
+    samples += framesThisTime;
+    count -= framesThisTime;
+  }
+}
+
 void playTone(
   float frequency,
   int durationMs
diff --git a/src/audio/audio.h b/src/audio/audio.h
index 49875d86..31be638e 100644
--- a/src/audio/audio.h
+++ b/src/audio/audio.h
@@ -5,6 +5,8 @@
 extern I2SClass I2S;
 
 bool initAudioStorage();
+// Volume-scaled, duplicated to both I2S slots. Blocks until the DMA buffer accepts it.
+void writeMonoToSpeaker(const int16_t* samples, size_t count);
 void playTone(
   float frequency,
   int durationMs
diff --git a/src/audio/wav_parser.cpp b/src/audio/wav_parser.cpp
new file mode 100644
index 00000000..7fd06876
--- /dev/null
+++ b/src/audio/wav_parser.cpp
@@ -0,0 +1,237 @@
+#include "audio/wav_parser.h"
+
+#include <cstdio>
+#include <cstring>
+
+namespace {
+
+uint16_t readLe16(const uint8_t* bytes) {
+  return static_cast<uint16_t>(bytes[0] | (bytes[1] << 8));
+}
+
+uint32_t readLe32(const uint8_t* bytes) {
+  return static_cast<uint32_t>(bytes[0]) |
+         (static_cast<uint32_t>(bytes[1]) << 8) |
+         (static_cast<uint32_t>(bytes[2]) << 16) |
+         (static_cast<uint32_t>(bytes[3]) << 24);
+}
+
+constexpr uint16_t kFormatPcm = 1;
+constexpr uint16_t kFormatExtensible = 0xFFFE;
+
+}  // namespace
+
+WavStreamParser::WavStreamParser(uint32_t sampleRate, Sink& sink)
+  : sink_(sink), sampleRate_(sampleRate) {}
+
+void WavStreamParser::feed(const uint8_t* bytes, size_t length) {
+  while (length > 0 && state_ != State::Failed) {
+    size_t used = 0;
+
+    switch (state_) {
+      case State::RiffHeader:
+        used = fillHeader(bytes, length);
+        if (headerFill_ == headerNeed_) {
+          if (memcmp(header_, "RIFF", 4) != 0 || memcmp(header_ + 8, "WAVE", 4) != 0) {
+            fail("not a WAV file");
+            break;
+          }
+          state_ = State::ChunkHeader;
+          headerFill_ = 0;
+          headerNeed_ = 8;
+        }
+        break;
+
+      case State::ChunkHeader:
+        used = fillHeader(bytes, length);
+        if (headerFill_ == headerNeed_) {
+          beginChunk();
+        }
+        break;
+
+      case State::Format:
+        used = fillHeader(bytes, length);
+        if (headerFill_ == headerNeed_) {
+          parseFormat();
+        }
+        break;
+
+      case State::Skip:
+        if (chunkRemaining_ == 0) {
+          endChunk();
+          break;
+        }
+        used = length < chunkRemaining_ ? length : chunkRemaining_;
+        chunkRemaining_ -= used;
+        break;
+
+      case State::Pcm:
+        used = consumePcm(bytes, length);
+        break;
+
+      case State::Trailer:
+        used = length;
+        break;
+
+      case State::Failed:
+        break;
+    }
+
+    bytes += used;
+    length -= used;
+  }
+
+  flush();
+}
+
+void WavStreamParser::finish() {
+  flush();
+
+  if (state_ == State::RiffHeader && headerFill_ > 0) {
+    fail("not a WAV file");
+  } else if (state_ != State::Failed && !reachedPcm_) {
+    fail("no audio data");
+  }
+}
+
+bool WavStreamParser::failed() const {
+  return state_ == State::Failed;
+}
+
+const char* WavStreamParser::error() const {
+  return failed() ? message_ : nullptr;
+}
+
+bool WavStreamParser::reachedPcm() const {
+  return reachedPcm_;
+}
+
+uint32_t WavStreamParser::samplesDelivered() const {
+  return samplesDelivered_;
+}
+
+size_t WavStreamParser::fillHeader(const uint8_t* bytes, size_t length) {
+  const size_t wanted = headerNeed_ - headerFill_;
+  const size_t used = length < wanted ? length : wanted;
+  memcpy(header_ + headerFill_, bytes, used);
+  headerFill_ += used;
+  return used;
+}
+
+void WavStreamParser::beginChunk() {
+  const uint32_t size = readLe32(header_ + 4);
+  headerFill_ = 0;
+  chunkPadded_ = (size & 1u) != 0;
+
+  if (memcmp(header_, "fmt ", 4) == 0) {
+    if (size < 16) {
+      fail("malformed fmt chunk");
+      return;
+    }
+    headerNeed_ = size < kHeaderBytes ? size : kHeaderBytes;
+    chunkRemaining_ = size - headerNeed_;
+    state_ = State::Format;
+    return;
+  }
+
+  if (memcmp(header_, "data", 4) == 0) {
+    if (!formatSeen_) {
+      fail("data chunk before fmt chunk");
+      return;
+    }
+    // Streaming encoders write 0 or 0xFFFFFFFF when the length is not known up front.
+    chunkRemaining_ = size == 0 ? kUnknownLength : size;
+    reachedPcm_ = true;
+    state_ = State::Pcm;
+    return;
+  }
+
+  chunkRemaining_ = size;
+  state_ = State::Skip;
+}
+
+void WavStreamParser::parseFormat() {
+  uint16_t format = readLe16(header_);
+  const uint16_t channels = readLe16(header_ + 2);
+  const uint32_t rate = readLe32(header_ + 4);
+  const uint16_t bits = readLe16(header_ + 14);
+
+  if (format == kFormatExtensible && headerNeed_ >= 26) {
+    format = readLe16(header_ + 24);
+  }
+
+  if (format != kFormatPcm || channels != 1 || bits != 16 || rate != sampleRate_) {
+    snprintf(
+      message_,
+      sizeof(message_),
+      "expected 16-bit mono PCM at %lu Hz",
+      static_cast<unsigned long>(sampleRate_)
+    );
+    state_ = State::Failed;
+    return;
+  }
+
+  formatSeen_ = true;
+  state_ = State::Skip;
+}
+
+void WavStreamParser::endChunk() {
+  if (chunkPadded_) {
+    chunkPadded_ = false;
+    chunkRemaining_ = 1;
+    state_ = State::Skip;
+    return;
+  }
+
+  state_ = State::ChunkHeader;
+  headerFill_ = 0;
+  headerNeed_ = 8;
+}
+
+size_t WavStreamParser::consumePcm(const uint8_t* bytes, size_t length) {
+  const bool unbounded = chunkRemaining_ == kUnknownLength;
+  const size_t used = unbounded || length < chunkRemaining_ ? length : chunkRemaining_;
+
+  for (size_t i = 0; i < used; i++) {
+    if (!hasCarry_) {
+      carry_ = bytes[i];
+      hasCarry_ = true;
+      continue;
+    }
+
+    pushSample(static_cast<int16_t>(carry_ | (bytes[i] << 8)));
+    hasCarry_ = false;
+  }
+
+  if (!unbounded) {
+    chunkRemaining_ -= used;
+    if (chunkRemaining_ == 0) {
+      state_ = State::Trailer;
+    }
+  }
+
+  return used;
+}
+
+void WavStreamParser::pushSample(int16_t sample) {
+  batch_[batchFill_++] = sample;
+
+  if (batchFill_ == kBatchSamples) {
+    flush();
+  }
+}
+
+void WavStreamParser::flush() {
+  if (batchFill_ == 0) {
+    return;
+  }
+
+  sink_.onPcm(batch_, batchFill_);
+  samplesDelivered_ += batchFill_;
+  batchFill_ = 0;
+}
+
+void WavStreamParser::fail(const char* message) {
+  snprintf(message_, sizeof(message_), "%s", message);
+  state_ = State::Failed;
+}
diff --git a/src/audio/wav_parser.h b/src/audio/wav_parser.h
new file mode 100644
index 00000000..50e35c39
--- /dev/null
+++ b/src/audio/wav_parser.h
@@ -0,0 +1,73 @@
+#pragma once
+
+#include <cstddef>
+#include <cstdint>
+
+// Incremental RIFF/WAVE reader for bodies that arrive in arbitrary slices.
+// Accepts 16-bit mono PCM at one sample rate and hands samples to a sink as
+// soon as they are complete; nothing beyond one small batch is buffered.
+class WavStreamParser {
+public:
+  class Sink {
+  public:
+    virtual void onPcm(const int16_t* samples, size_t count) = 0;
+
+  protected:
+    ~Sink() = default;
+  };
+
+  WavStreamParser(uint32_t sampleRate, Sink& sink);
+
+  void feed(const uint8_t* bytes, size_t length);
+  void finish();
+
+  bool failed() const;
+  // Human-readable reason when failed(), else nullptr.
+  const char* error() const;
+  bool reachedPcm() const;
+  uint32_t samplesDelivered() const;
+
+private:
+  enum class State {
+    RiffHeader,
+    ChunkHeader,
+    Format,
+    Skip,
+    Pcm,
+    Trailer,
+    Failed
+  };
+
+  static constexpr size_t kHeaderBytes = 40;
+  static constexpr size_t kBatchSamples = 256;
+  static constexpr uint32_t kUnknownLength = 0xFFFFFFFFu;
+
+  Sink& sink_;
+  uint32_t sampleRate_;
+  State state_ = State::RiffHeader;
+  char message_[48] = {};
+
+  uint8_t header_[kHeaderBytes] = {};
+  size_t headerFill_ = 0;
+  size_t headerNeed_ = 12;
+
+  uint32_t chunkRemaining_ = 0;
+  bool chunkPadded_ = false;
+  bool formatSeen_ = false;
+  bool reachedPcm_ = false;
+
+  int16_t batch_[kBatchSamples] = {};
+  size_t batchFill_ = 0;
+  bool hasCarry_ = false;
+  uint8_t carry_ = 0;
+  uint32_t samplesDelivered_ = 0;
+
+  size_t fillHeader(const uint8_t* bytes, size_t length);
+  void beginChunk();
+  void parseFormat();
+  void endChunk();
+  size_t consumePcm(const uint8_t* bytes, size_t length);
+  void pushSample(int16_t sample);
+  void flush();
+  void fail(const char* message);
+};
diff --git a/src/audio/wav_stream.cpp b/src/audio/wav_stream.cpp
index 236e1d80..0a6cbab6 100644
--- a/src/audio/wav_stream.cpp
+++ b/src/audio/wav_stream.cpp
@@ -96,52 +96,19 @@ bool skipWavPcmData(File& file) {
 }
 
 bool pumpWavChunk(File& file) {
-  int16_t buffer[kAudioFrames * 2];
-  uint8_t pcmBytes[kAudioFrames * 2];
+  int16_t samples[kAudioFrames];
 
   const size_t bytesRead =
     file.read(
-      pcmBytes,
-      sizeof(pcmBytes)
+      reinterpret_cast<uint8_t*>(samples),
+      sizeof(samples)
     );
 
   if (bytesRead < 2) {
     return false;
   }
 
-  const int framesThisTime =
-    (int)(bytesRead / 2);
-
-  const uint8_t volume = settingsVolume();
-
-  for (int i = 0; i < framesThisTime; i++) {
-    const int16_t raw =
-      (int16_t)(
-        pcmBytes[i * 2] |
-        (pcmBytes[i * 2 + 1] << 8)
-      );
-
-    int32_t scaled =
-      (static_cast<int32_t>(raw) * volume) / 100;
-
-    if (scaled > 32767) {
-      scaled = 32767;
-    } else if (scaled < -32768) {
-      scaled = -32768;
-    }
-
-    const int16_t sample = static_cast<int16_t>(scaled);
-
-    buffer[i * 2] = sample;
-    buffer[i * 2 + 1] = sample;
-  }
-
-  I2S.write(
-    (uint8_t*)buffer,
-    framesThisTime *
-    2 *
-    sizeof(int16_t)
-  );
+  writeMonoToSpeaker(samples, bytesRead / 2);
 
   return file.available() > 0;
 }
diff --git a/src/http/json.cpp b/src/http/json.cpp
index 6e847936..910225e8 100644
--- a/src/http/json.cpp
+++ b/src/http/json.cpp
@@ -55,16 +55,14 @@ void httpSendCorsPreflight(WebServer& server) {
   server.send(204);
 }
 
-bool httpRequireApiAuth(WebServer& server) {
-  if (!settingsAccessTokenSet()) {
-    return true;
-  }
+bool httpApiAuthorized(WebServer& server) {
+  return !settingsAccessTokenSet() ||
+         (server.hasHeader("Authorization") &&
+          bearerTokenMatches(server.header("Authorization"), settingsAccessToken()));
+}
 
-  if (!server.hasHeader("Authorization") ||
-      !bearerTokenMatches(
-        server.header("Authorization"),
-        settingsAccessToken()
-      )) {
+bool httpRequireApiAuth(WebServer& server) {
+  if (!httpApiAuthorized(server)) {
     httpSendJson(
       server,
       401,
diff --git a/src/http/json.h b/src/http/json.h
index f5c0aa35..faec41ee 100644
--- a/src/http/json.h
+++ b/src/http/json.h
@@ -6,6 +6,8 @@ void httpSendJson(WebServer& server, int code, const char* body);
 void httpSendHtml(WebServer& server, int code, const char* body);
 void httpSendCorsPreflight(WebServer& server);
 
+bool httpApiAuthorized(WebServer& server);
+
 // Returns false and sends 401 when access token is configured and missing/wrong.
 bool httpRequireApiAuth(WebServer& server);
 
diff --git a/src/http/play_handlers.cpp b/src/http/play_handlers.cpp
new file mode 100644
index 00000000..0ae06f03
--- /dev/null
+++ b/src/http/play_handlers.cpp
@@ -0,0 +1,118 @@
+#include "http/play_handlers.h"
+
+#include <Arduino.h>
+
+#include <cstdio>
+#include <optional>
+
+#include "animation.h"
+#include "audio/audio.h"
+#include "audio/wav_parser.h"
+#include "hardware/rgb.h"
+#include "http/json.h"
+#include "pins.h"
+#include "settings/settings.h"
+#include "serial_log.h"
+
+namespace {
+
+// One POST /play request. loop() is blocked while the body streams, so the
+// session keeps animation, eyes and LED moving between speaker writes.
+class PlaySession : public WavStreamParser::Sink {
+public:
+  void begin(WebServer& server) {
+    parser_.reset();
+    rejectCode_ = 0;
+
+    if (!settingsWifiConfigured()) {
+      reject(503, "{\"ok\":false,\"error\":\"wifi not configured\"}");
+      return;
+    }
+
+    if (!httpApiAuthorized(server)) {
+      reject(401, "{\"ok\":false,\"error\":\"unauthorized\"}");
+      return;
+    }
+
+    stopAllWavPlayback();
+    parser_.emplace(SAMPLE_RATE, *this);
+    serialLogPrintln("[play] start");
+  }
+
+  void feed(const uint8_t* bytes, size_t length) {
+    if (parser_ && !parser_->failed()) {
+      parser_->feed(bytes, length);
+    }
+  }
+
+  void end() {
+    if (parser_) {
+      parser_->finish();
+      serialLogPrint("[play] end ms=");
+      serialLogPrintln(playedMs());
+    }
+  }
+
+  void respond(WebServer& server) {
+    if (rejectCode_ != 0) {
+      httpSendJson(server, rejectCode_, rejectBody_);
+      return;
+    }
+
+    char body[96];
+
+    if (parser_->failed()) {
+      snprintf(body, sizeof(body), "{\"ok\":false,\"error\":\"%s\"}", parser_->error());
+      httpSendJson(server, 415, body);
+      return;
+    }
+
+    snprintf(body, sizeof(body), "{\"ok\":true,\"played_ms\":%lu}", static_cast<unsigned long>(playedMs()));
+    httpSendJson(server, 200, body);
+  }
+
+  void onPcm(const int16_t* samples, size_t count) override {
+    writeMonoToSpeaker(samples, count);
+    updateAnimation();
+    updateRgb(millis());
+  }
+
+private:
+  std::optional<WavStreamParser> parser_;
+  int rejectCode_ = 0;
+  const char* rejectBody_ = nullptr;
+
+  void reject(int code, const char* body) {
+    rejectCode_ = code;
+    rejectBody_ = body;
+  }
+
+  uint32_t playedMs() const {
+    return static_cast<uint32_t>(parser_->samplesDelivered() * 1000ULL / SAMPLE_RATE);
+  }
+};
+
+PlaySession g_session;
+
+}  // namespace
+
+void handlePlayBody(WebServer& server) {
+  HTTPRaw& raw = server.raw();
+
+  switch (raw.status) {
+    case RAW_START:
+      g_session.begin(server);
+      break;
+    case RAW_WRITE:
+      g_session.feed(raw.buf, raw.currentSize);
+      break;
+    case RAW_END:
+    case RAW_ABORTED:
+      g_session.end();
+      break;
+  }
+}
+
+void handlePlayDone(WebServer& server) {
+  g_session.respond(server);
+}
diff --git a/src/http/play_handlers.h b/src/http/play_handlers.h
new file mode 100644
index 00000000..f22dc8f9
--- /dev/null
+++ b/src/http/play_handlers.h
@@ -0,0 +1,8 @@
+#pragma once
+
+#include <WebServer.h>
+
+// Called for each slice of the request body as it arrives.
+void handlePlayBody(WebServer& server);
+// Called once the whole body has been consumed.
+void handlePlayDone(WebServer& server);
diff --git a/src/http/routes.cpp b/src/http/routes.cpp
index 3ceae501..5c63467e 100644
--- a/src/http/routes.cpp
+++ b/src/http/routes.cpp
@@ -7,6 +7,7 @@
 #include "http/health_handlers.h"
 #include "http/index_page.h"
 #include "http/json.h"
+#include "http/play_handlers.h"
 #include "http/server_context.h"
 #include "http/settings_handlers.h"
 #include "http/setup_handlers.h"
@@ -83,6 +84,12 @@ void registerHttpRoutes() {
   server.on("/anim", HTTP_POST, []() {
     httpWithWifiAndApiAuth(httpServer(), handleAnimPost);
   });
+  server.on(
+    "/play",
+    HTTP_POST,
+    []() { handlePlayDone(httpServer()); },
+    []() { handlePlayBody(httpServer()); }
+  );
   server.on("/settings", HTTP_GET, []() {
     httpWithApiAuth(httpServer(), handleSettingsGet);
   });
diff --git a/src/http/settings_handlers.cpp b/src/http/settings_handlers.cpp
index 6ab9757a..909e4d7a 100644
--- a/src/http/settings_handlers.cpp
+++ b/src/http/settings_handlers.cpp
@@ -662,6 +662,6 @@ void handleSettingsReset(WebServer& server) {
 }
 
 bool isSettingsOrAnimPath(const String& uri) {
-  return uri == "/anim" || uri == "/settings" || uri == "/settings/reset" ||
+  return uri == "/anim" || uri == "/play" || uri == "/settings" || uri == "/settings/reset" ||
          uri == "/auth" || uri == "/setup/servo";
 }
diff --git a/test/test_wav_parser/test_wav_parser.cpp b/test/test_wav_parser/test_wav_parser.cpp
new file mode 100644
index 00000000..84952832
--- /dev/null
+++ b/test/test_wav_parser/test_wav_parser.cpp
@@ -0,0 +1,208 @@
+#include <unity.h>
+
+#include <cstring>
+#include <vector>
+
+#include "audio/wav_parser.h"
+
+namespace {
+
+constexpr uint32_t kRate = 44100;
+
+struct CollectingSink : WavStreamParser::Sink {
+  std::vector<int16_t> samples;
+
+  void onPcm(const int16_t* data, size_t count) override {
+    samples.insert(samples.end(), data, data + count);
+  }
+};
+
+void appendLe16(std::vector<uint8_t>& out, uint16_t value) {
+  out.push_back(value & 0xFF);
+  out.push_back(value >> 8);
+}
+
+void appendLe32(std::vector<uint8_t>& out, uint32_t value) {
+  for (int shift = 0; shift < 32; shift += 8) {
+    out.push_back((value >> shift) & 0xFF);
+  }
+}
+
+void appendChunk(std::vector<uint8_t>& out, const char* id, const std::vector<uint8_t>& body, uint32_t declaredSize) {
+  out.insert(out.end(), id, id + 4);
+  appendLe32(out, declaredSize);
+  out.insert(out.end(), body.begin(), body.end());
+  if (body.size() % 2 != 0) {
+    out.push_back(0);
+  }
+}
+
+std::vector<uint8_t> fmtBody(uint16_t channels, uint32_t rate) {
+  std::vector<uint8_t> body;
+  appendLe16(body, 1);
+  appendLe16(body, channels);
+  appendLe32(body, rate);
+  appendLe32(body, rate * channels * 2);
+  appendLe16(body, channels * 2);
+  appendLe16(body, 16);
+  return body;
+}
+
+std::vector<uint8_t> pcmBytes(const std::vector<int16_t>& samples) {
+  std::vector<uint8_t> body;
+  for (int16_t sample : samples) {
+    appendLe16(body, static_cast<uint16_t>(sample));
+  }
+  return body;
+}
+
+std::vector<uint8_t> wav(
+  const std::vector<int16_t>& samples,
+  uint32_t rate = kRate,
+  uint16_t channels = 1,
+  bool streamingDataSize = false
+) {
+  std::vector<uint8_t> out = {'R', 'I', 'F', 'F', 0, 0, 0, 0, 'W', 'A', 'V', 'E'};
+  appendChunk(out, "fmt ", fmtBody(channels, rate), 16);
+  const std::vector<uint8_t> pcm = pcmBytes(samples);
+  appendChunk(out, "data", pcm, streamingDataSize ? 0 : pcm.size());
+  return out;
+}
+
+void feedInSlices(WavStreamParser& parser, const std::vector<uint8_t>& bytes, size_t slice) {
+  for (size_t offset = 0; offset < bytes.size(); offset += slice) {
+    const size_t length = bytes.size() - offset < slice ? bytes.size() - offset : slice;
+    parser.feed(bytes.data() + offset, length);
+  }
+  parser.finish();
+}
+
+std::vector<int16_t> ramp(size_t count) {
+  std::vector<int16_t> samples;
+  for (size_t i = 0; i < count; i++) {
+    samples.push_back(static_cast<int16_t>(i * 37 - 20000));
+  }
+  return samples;
+}
+
+}  // namespace
+
+void test_delivers_samples_regardless_of_slicing() {
+  const std::vector<int16_t> samples = ramp(1000);
+  const std::vector<uint8_t> bytes = wav(samples);
+
+  for (size_t slice : {1u, 3u, 7u, 1436u}) {
+    CollectingSink sink;
+    WavStreamParser parser(kRate, sink);
+    feedInSlices(parser, bytes, slice);
+
+    TEST_ASSERT_FALSE(parser.failed());
+    TEST_ASSERT_EQUAL_UINT32(samples.size(), parser.samplesDelivered());
+    TEST_ASSERT_EQUAL_INT16_ARRAY(samples.data(), sink.samples.data(), samples.size());
+  }
+}
+
+void test_skips_unknown_chunks_including_padding() {
+  const std::vector<int16_t> samples = ramp(10);
+  std::vector<uint8_t> bytes = {'R', 'I', 'F', 'F', 0, 0, 0, 0, 'W', 'A', 'V', 'E'};
+  appendChunk(bytes, "LIST", {1, 2, 3}, 3);
+  appendChunk(bytes, "fmt ", fmtBody(1, kRate), 16);
+  appendChunk(bytes, "junk", {9, 9, 9, 9, 9}, 5);
+  const std::vector<uint8_t> pcm = pcmBytes(samples);
+  appendChunk(bytes, "data", pcm, pcm.size());
+
+  CollectingSink sink;
+  WavStreamParser parser(kRate, sink);
+  feedInSlices(parser, bytes, 2);
+
+  TEST_ASSERT_FALSE(parser.failed());
+  TEST_ASSERT_EQUAL_INT16_ARRAY(samples.data(), sink.samples.data(), samples.size());
+}
+
+void test_ignores_chunks_after_data() {
+  const std::vector<int16_t> samples = ramp(8);
+  std::vector<uint8_t> bytes = wav(samples);
+  appendChunk(bytes, "LIST", {1, 2, 3, 4}, 4);
+
+  CollectingSink sink;
+  WavStreamParser parser(kRate, sink);
+  feedInSlices(parser, bytes, 5);
+
+  TEST_ASSERT_FALSE(parser.failed());
+  TEST_ASSERT_EQUAL_size_t(samples.size(), sink.samples.size());
+}
+
+void test_streaming_data_size_plays_until_body_ends() {
+  const std::vector<int16_t> samples = ramp(300);
+
+  CollectingSink sink;
+  WavStreamParser parser(kRate, sink);
+  feedInSlices(parser, wav(samples, kRate, 1, true), 64);
+
+  TEST_ASSERT_FALSE(parser.failed());
+  TEST_ASSERT_EQUAL_size_t(samples.size(), sink.samples.size());
+}
+
+void test_rejects_other_sample_rate() {
+  CollectingSink sink;
+  WavStreamParser parser(kRate, sink);
+  feedInSlices(parser, wav(ramp(10), 22050), 1436);
+
+  TEST_ASSERT_TRUE(parser.failed());
+  TEST_ASSERT_EQUAL_STRING("expected 16-bit mono PCM at 44100 Hz", parser.error());
+  TEST_ASSERT_TRUE(sink.samples.empty());
+}
+
+void test_rejects_stereo() {
+  CollectingSink sink;
+  WavStreamParser parser(kRate, sink);
+  feedInSlices(parser, wav(ramp(10), kRate, 2), 1436);
+
+  TEST_ASSERT_TRUE(parser.failed());
+  TEST_ASSERT_TRUE(sink.samples.empty());
+}
+
+void test_rejects_non_wav() {
+  const char* text = "{\"name\":\"ring\"}";
+  CollectingSink sink;
+  WavStreamParser parser(kRate, sink);
+  parser.feed(reinterpret_cast<const uint8_t*>(text), strlen(text));
+  parser.finish();
+
+  TEST_ASSERT_EQUAL_STRING("not a WAV file", parser.error());
+}
+
+void test_body_shorter_than_header_is_not_wav() {
+  const uint8_t bytes[] = {'h', 'e', 'l', 'l', 'o'};
+  CollectingSink sink;
+  WavStreamParser parser(kRate, sink);
+  parser.feed(bytes, sizeof(bytes));
+  parser.finish();
+
+  TEST_ASSERT_EQUAL_STRING("not a WAV file", parser.error());
+}
+
+void test_body_without_data_chunk_fails() {
+  std::vector<uint8_t> bytes = {'R', 'I', 'F', 'F', 0, 0, 0, 0, 'W', 'A', 'V', 'E'};
+  appendChunk(bytes, "fmt ", fmtBody(1, kRate), 16);
+
+  CollectingSink sink;
+  WavStreamParser parser(kRate, sink);
+  feedInSlices(parser, bytes, 1436);
+
+  TEST_ASSERT_EQUAL_STRING("no audio data", parser.error());
+}
+
+int main(int, char**) {
+  UNITY_BEGIN();
+  RUN_TEST(test_delivers_samples_regardless_of_slicing);
+  RUN_TEST(test_skips_unknown_chunks_including_padding);
+  RUN_TEST(test_ignores_chunks_after_data);
+  RUN_TEST(test_streaming_data_size_plays_until_body_ends);
+  RUN_TEST(test_rejects_other_sample_rate);
+  RUN_TEST(test_rejects_stereo);
+  RUN_TEST(test_rejects_non_wav);
+  RUN_TEST(test_body_shorter_than_header_is_not_wav);
+  RUN_TEST(test_body_without_data_chunk_fails);
+  return UNITY_END();
+}

From d6c996ead1f5abb4c19cabec193018bfc0619f79 Mon Sep 17 00:00:00 2001
From: shodan <mega@ioexception.at>
Date: Sat, 3 Oct 2026 23:06:22 +0200
Subject: [PATCH 02/21] feat(anim): drive animation from an X-Anim timeline
 during POST /play

The X-Anim request header carries a JSON array of steps run against the
audio playback clock:

  ["sleep", ms]                  advance the script clock
  ["preset", name]               run an /anim animation without its sound
  ["move", servo, to, ms?]       reach pose position -1..1 within ms
  ["eyes", mode]                 switch the eye mode

Moves do not block, so moves without a sleep between them run together.
The whole timeline is validated before any audio plays and rejected with
400 and the failing step. Presets that play their own audio, or sleep,
are not allowed. When the clip ends the previous continuous animation is
restored, otherwise the robot returns to idle.

WEBSERVER_MAX_LINE_LEN is raised to 8192 so the header fits about 250
steps.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 platformio.ini                       |   5 ++
 src/animation.h                      |   2 +
 src/animation/controller.cpp         |   4 +
 src/animation/timeline.cpp           | 110 ++++++++++++++++++++++++++
 src/animation/timeline.h             |  53 +++++++++++++
 src/animation/timeline_player.cpp    | 111 +++++++++++++++++++++++++++
 src/animation/timeline_player.h      |  28 +++++++
 src/audio/wav_parser.h               |   2 +-
 src/http/http_server.cpp             |   4 +-
 src/http/json.cpp                    |   2 +-
 src/http/play_handlers.cpp           |  70 +++++++++++++----
 test/test_timeline/test_timeline.cpp | 101 ++++++++++++++++++++++++
 12 files changed, 473 insertions(+), 19 deletions(-)
 create mode 100644 src/animation/timeline.cpp
 create mode 100644 src/animation/timeline.h
 create mode 100644 src/animation/timeline_player.cpp
 create mode 100644 src/animation/timeline_player.h
 create mode 100644 test/test_timeline/test_timeline.cpp

diff --git a/platformio.ini b/platformio.ini
index f950b4a7..a1787c34 100644
--- a/platformio.ini
+++ b/platformio.ini
@@ -23,11 +23,14 @@ lib_deps =
     adafruit/Adafruit PWM Servo Driver Library
     adafruit/Adafruit GFX Library
     adafruit/Adafruit SSD1306
+    bblanchon/ArduinoJson@^7.4.3
 
 build_flags =
     -D ARDUINO_USB_MODE=1
     -D ARDUINO_USB_CDC_ON_BOOT=1
     -D SSD1306_NO_SPLASH
+    ; Room for the X-Anim header on POST /play (about 250 steps).
+    -D WEBSERVER_MAX_LINE_LEN=8192
 
 board_build.partitions = partitions.csv
 board_build.filesystem = littlefs
@@ -47,11 +50,13 @@ test_ignore = *
 platform = native
 test_framework = unity
 test_build_src = true
+lib_deps = bblanchon/ArduinoJson@^7.4.3
 build_src_filter =
     -<**/*.*>
     +<settings/validate.cpp>
     +<display/eyes/styles/eye_style_ids.cpp>
     +<audio/wav_parser.cpp>
+    +<animation/timeline.cpp>
 build_flags = -std=c++17 -Iinclude -Isrc
 
 ; Opt-in OLED-only application. Building does not upload or change robot settings.
diff --git a/src/animation.h b/src/animation.h
index 4000337f..9095681f 100644
--- a/src/animation.h
+++ b/src/animation.h
@@ -16,6 +16,8 @@ enum class AnimationId {
 };
 
 void setAnimation(AnimationId id);
+// Skips the minimum hold and restarts `id` even when it is already running.
+void setAnimationImmediately(AnimationId id);
 void finishAnimation(uint32_t nowMs);
 AnimationId getAnimation();
 bool hasPendingAnimation();
diff --git a/src/animation/controller.cpp b/src/animation/controller.cpp
index c2c6fab6..87e7bfbd 100644
--- a/src/animation/controller.cpp
+++ b/src/animation/controller.cpp
@@ -109,6 +109,10 @@ void setAnimation(AnimationId id) {
   serialLogPrintln(holdLeftMs);
 }
 
+void setAnimationImmediately(AnimationId id) {
+  applyAnimation(id, millis());
+}
+
 void finishAnimation(uint32_t nowMs) {
   applyAnimation(AnimationId::None, nowMs);
 }
diff --git a/src/animation/timeline.cpp b/src/animation/timeline.cpp
new file mode 100644
index 00000000..28d98d91
--- /dev/null
+++ b/src/animation/timeline.cpp
@@ -0,0 +1,110 @@
+#include "animation/timeline.h"
+
+#include <ArduinoJson.h>
+
+#include <cstdio>
+#include <cstring>
+#include <strings.h>
+
+#include "servos.h"
+
+namespace {
+
+bool findServo(const char* name, uint8_t& index) {
+  for (uint8_t i = 0; i < SERVO_COUNT; i++) {
+    if (strcasecmp(SERVO_SPECS[i].name, name) == 0) {
+      index = i;
+      return true;
+    }
+  }
+
+  return false;
+}
+
+}  // namespace
+
+std::optional<Timeline> Timeline::parse(
+  const char* json,
+  size_t length,
+  const Names& names,
+  char* error,
+  size_t errorSize
+) {
+  JsonDocument doc;
+
+  if (deserializeJson(doc, json, length) != DeserializationError::Ok || !doc.is<JsonArrayConst>()) {
+    snprintf(error, errorSize, "X-Anim is not a JSON array");
+    return std::nullopt;
+  }
+
+  JsonArrayConst items = doc.as<JsonArrayConst>();
+
+  if (items.size() > kMaxSteps) {
+    snprintf(error, errorSize, "anim has more than %u steps", static_cast<unsigned>(kMaxSteps));
+    return std::nullopt;
+  }
+
+  Timeline timeline;
+  uint32_t atMs = 0;
+  size_t index = 0;
+
+  for (JsonArrayConst item : items) {
+    const char* command = item[0].as<const char*>();
+
+    if (command == nullptr) {
+      snprintf(error, errorSize, "step %u: expected [command, ...]", static_cast<unsigned>(index));
+      return std::nullopt;
+    }
+
+    if (strcmp(command, "sleep") == 0) {
+      if (!item[1].is<uint32_t>() || item[1].as<uint32_t>() > kMaxSleepMs) {
+        snprintf(error, errorSize, "step %u: sleep needs 0..%lu ms", static_cast<unsigned>(index), static_cast<unsigned long>(kMaxSleepMs));
+        return std::nullopt;
+      }
+      atMs += item[1].as<uint32_t>();
+    } else if (strcmp(command, "preset") == 0 || strcmp(command, "eyes") == 0) {
+      const bool preset = command[0] == 'p';
+      const char* name = item[1].as<const char*>();
+      uint8_t id = 0;
+      const char* reason = name == nullptr ? "missing name" : (preset ? names.preset : names.eyes)(name, id);
+
+      if (reason != nullptr) {
+        snprintf(error, errorSize, "step %u: %s %s", static_cast<unsigned>(index), command, reason);
+        return std::nullopt;
+      }
+      timeline.steps_.push_back({atMs, preset ? Kind::Preset : Kind::Eyes, id, 0.0f, 0});
+    } else if (strcmp(command, "move") == 0) {
+      const char* servo = item[1].as<const char*>();
+      uint8_t servoIndex = 0;
+
+      if (servo == nullptr || !findServo(servo, servoIndex)) {
+        snprintf(error, errorSize, "step %u: unknown servo", static_cast<unsigned>(index));
+        return std::nullopt;
+      }
+      const bool hasDuration = !item[3].isNull();
+      if (!item[2].is<float>() || (hasDuration && (!item[3].is<uint32_t>() || item[3].as<uint32_t>() > kMaxSleepMs))) {
+        snprintf(error, errorSize, "step %u: move needs a position -1..1 and optional duration ms", static_cast<unsigned>(index));
+        return std::nullopt;
+      }
+
+      timeline.steps_.push_back({
+        atMs,
+        Kind::Move,
+        servoIndex,
+        servoSaturateNorm(item[2].as<float>()),
+        hasDuration ? item[3].as<uint32_t>() : 0
+      });
+    } else {
+      snprintf(error, errorSize, "step %u: unknown command", static_cast<unsigned>(index));
+      return std::nullopt;
+    }
+
+    index++;
+  }
+
+  return timeline;
+}
+
+const std::vector<Timeline::Step>& Timeline::steps() const {
+  return steps_;
+}
diff --git a/src/animation/timeline.h b/src/animation/timeline.h
new file mode 100644
index 00000000..980a358f
--- /dev/null
+++ b/src/animation/timeline.h
@@ -0,0 +1,53 @@
+#pragma once
+
+#include <cstddef>
+#include <cstdint>
+#include <optional>
+#include <vector>
+
+// A choreography sent alongside streamed audio: a JSON array of steps such as
+// ["sleep", 500], ["preset", "typing"], ["move", "head", 0.6, 300], ["eyes", "thinking"].
+// Sleeps are folded into each step's start time, measured in playback milliseconds.
+// Moves do not block: moves without a sleep between them run together.
+class Timeline {
+public:
+  enum class Kind : uint8_t {
+    Preset,
+    Move,
+    Eyes
+  };
+
+  struct Step {
+    uint32_t atMs;
+    Kind kind;
+    // Preset or eye-mode id from the resolver, or a servo index for Move.
+    uint8_t target;
+    float to;
+    // Time a Move should take to arrive; 0 moves at the maximum servo speed.
+    uint32_t durationMs;
+  };
+
+  // Returns nullptr and sets `id` when `name` is usable, else the reason it is not.
+  using NameResolver = const char* (*)(const char* name, uint8_t& id);
+
+  struct Names {
+    NameResolver preset;
+    NameResolver eyes;
+  };
+
+  static constexpr size_t kMaxSteps = 256;
+  static constexpr uint32_t kMaxSleepMs = 600000;
+
+  static std::optional<Timeline> parse(
+    const char* json,
+    size_t length,
+    const Names& names,
+    char* error,
+    size_t errorSize
+  );
+
+  const std::vector<Step>& steps() const;
+
+private:
+  std::vector<Step> steps_;
+};
diff --git a/src/animation/timeline_player.cpp b/src/animation/timeline_player.cpp
new file mode 100644
index 00000000..98398fa9
--- /dev/null
+++ b/src/animation/timeline_player.cpp
@@ -0,0 +1,111 @@
+#include "animation/timeline_player.h"
+
+#include <Arduino.h>
+
+#include <cmath>
+#include <cstring>
+
+#include "animation/registry.h"
+#include "display/eyes.h"
+#include "hardware/servo_wrapper.h"
+#include "network/wifi_connect.h"
+
+namespace {
+
+const char* resolvePreset(const char* name, uint8_t& id) {
+  AnimationId anim;
+
+  if (!parseAnimationName(name, anim)) {
+    return "unknown name";
+  }
+
+  switch (anim) {
+    case AnimationId::None:
+    case AnimationId::Typing:
+    case AnimationId::Reading:
+    case AnimationId::Thinking:
+    case AnimationId::Wakeup:
+      id = static_cast<uint8_t>(anim);
+      return nullptr;
+    default:
+      return "not available during playback";
+  }
+}
+
+const char* resolveEyes(const char* name, uint8_t& id) {
+  AnimationId anim;
+
+  if (strcmp(name, "idle") == 0) {
+    anim = AnimationId::None;
+  } else if (!parseAnimationName(name, anim)) {
+    return "unknown name";
+  }
+
+  id = static_cast<uint8_t>(modeByAnimId(anim)->eyeMode);
+  return nullptr;
+}
+
+const Timeline::Names kNames = {resolvePreset, resolveEyes};
+
+}  // namespace
+
+const Timeline::Names& TimelinePlayer::names() {
+  return kNames;
+}
+
+TimelinePlayer::TimelinePlayer(Timeline timeline)
+  : timeline_(std::move(timeline)), previous_(getAnimation()) {}
+
+void TimelinePlayer::advance(uint32_t playedMs) {
+  const auto& steps = timeline_.steps();
+
+  while (next_ < steps.size() && steps[next_].atMs <= playedMs) {
+    run(steps[next_++]);
+  }
+}
+
+void TimelinePlayer::update() {
+  if (!manualServos_) {
+    updateAnimation();
+    return;
+  }
+
+  updateAllServos();
+
+  if (!wifiProvisioningMode()) {
+    updateEyes(millis());
+  }
+}
+
+void TimelinePlayer::finish() {
+  setAnimationImmediately(animationIsContinuous(previous_) ? previous_ : AnimationId::None);
+}
+
+void TimelinePlayer::run(const Timeline::Step& step) {
+  switch (step.kind) {
+    case Timeline::Kind::Preset:
+      manualServos_ = false;
+      setAnimationImmediately(static_cast<AnimationId>(step.target));
+      break;
+
+    case Timeline::Kind::Eyes:
+      setEyeMode(static_cast<EyeMode>(step.target), millis());
+      break;
+
+    case Timeline::Kind::Move: {
+      manualServos_ = true;
+      ensureAllServoOutputs();
+
+      ServoWrapper& servo = servoAt(step.target);
+      float speed = SERVO_MAX_SPEED_DEG_S;
+
+      if (step.durationMs > 0) {
+        const float distance = fabsf(servoNormToDeg(step.target, step.to) - servo.angle());
+        speed = fminf(SERVO_MAX_SPEED_DEG_S, fmaxf(1.0f, distance * 1000.0f / step.durationMs));
+      }
+
+      servo.setNormTarget(step.to, speed);
+      break;
+    }
+  }
+}
diff --git a/src/animation/timeline_player.h b/src/animation/timeline_player.h
new file mode 100644
index 00000000..75777c1a
--- /dev/null
+++ b/src/animation/timeline_player.h
@@ -0,0 +1,28 @@
+#pragma once
+
+#include <cstdint>
+
+#include "animation.h"
+#include "animation/timeline.h"
+
+// Runs a Timeline against the audio playback clock while loop() is blocked by
+// the stream, then hands the robot back to the animation that was running.
+class TimelinePlayer {
+public:
+  static const Timeline::Names& names();
+
+  explicit TimelinePlayer(Timeline timeline);
+
+  void advance(uint32_t playedMs);
+  void update();
+  void finish();
+
+private:
+  Timeline timeline_;
+  size_t next_ = 0;
+  // A move takes the joints away from the preset until the next preset step.
+  bool manualServos_ = false;
+  AnimationId previous_;
+
+  void run(const Timeline::Step& step);
+};
diff --git a/src/audio/wav_parser.h b/src/audio/wav_parser.h
index 50e35c39..35e58e8c 100644
--- a/src/audio/wav_parser.h
+++ b/src/audio/wav_parser.h
@@ -45,7 +45,7 @@ class WavStreamParser {
   Sink& sink_;
   uint32_t sampleRate_;
   State state_ = State::RiffHeader;
-  char message_[48] = {};
+  char message_[80] = {};
 
   uint8_t header_[kHeaderBytes] = {};
   size_t headerFill_ = 0;
diff --git a/src/http/http_server.cpp b/src/http/http_server.cpp
index 8abbde43..adcb1e86 100644
--- a/src/http/http_server.cpp
+++ b/src/http/http_server.cpp
@@ -17,8 +17,8 @@ void startHttpServer() {
 
   refreshMdnsHostname();
 
-  static const char* kCollectHeaders[] = {"Authorization"};
-  server.collectHeaders(kCollectHeaders, 1);
+  static const char* kCollectHeaders[] = {"Authorization", "X-Anim"};
+  server.collectHeaders(kCollectHeaders, 2);
 
   registerHttpRoutes();
   server.begin();
diff --git a/src/http/json.cpp b/src/http/json.cpp
index 910225e8..b77f0632 100644
--- a/src/http/json.cpp
+++ b/src/http/json.cpp
@@ -8,7 +8,7 @@ namespace {
 
 void sendCorsHeaders(WebServer& server) {
   server.sendHeader("Access-Control-Allow-Origin", "*");
-  server.sendHeader("Access-Control-Allow-Headers", "Authorization");
+  server.sendHeader("Access-Control-Allow-Headers", "Authorization, X-Anim");
   server.sendHeader(
     "Access-Control-Allow-Methods",
     "GET, POST, OPTIONS"
diff --git a/src/http/play_handlers.cpp b/src/http/play_handlers.cpp
index 0ae06f03..4ef19eed 100644
--- a/src/http/play_handlers.cpp
+++ b/src/http/play_handlers.cpp
@@ -6,6 +6,8 @@
 #include <optional>
 
 #include "animation.h"
+#include "animation/timeline.h"
+#include "animation/timeline_player.h"
 #include "audio/audio.h"
 #include "audio/wav_parser.h"
 #include "hardware/rgb.h"
@@ -22,25 +24,33 @@ class PlaySession : public WavStreamParser::Sink {
 public:
   void begin(WebServer& server) {
     parser_.reset();
+    player_.reset();
     rejectCode_ = 0;
+    samplesWritten_ = 0;
 
     if (!settingsWifiConfigured()) {
-      reject(503, "{\"ok\":false,\"error\":\"wifi not configured\"}");
+      reject(503, "wifi not configured");
       return;
     }
 
     if (!httpApiAuthorized(server)) {
-      reject(401, "{\"ok\":false,\"error\":\"unauthorized\"}");
+      reject(401, "unauthorized");
       return;
     }
 
     stopAllWavPlayback();
     parser_.emplace(SAMPLE_RATE, *this);
     serialLogPrintln("[play] start");
+
+    const String& header = server.header("X-Anim");
+
+    if (header.length() > 0 && acceptTimeline(header.c_str(), header.length()) != nullptr) {
+      reject(400, error_);
+    }
   }
 
   void feed(const uint8_t* bytes, size_t length) {
-    if (parser_ && !parser_->failed()) {
+    if (rejectCode_ == 0 && parser_ && !parser_->failed()) {
       parser_->feed(bytes, length);
     }
   }
@@ -51,44 +61,74 @@ class PlaySession : public WavStreamParser::Sink {
       serialLogPrint("[play] end ms=");
       serialLogPrintln(playedMs());
     }
+
+    if (player_) {
+      player_->finish();
+      player_.reset();
+    }
   }
 
   void respond(WebServer& server) {
     if (rejectCode_ != 0) {
-      httpSendJson(server, rejectCode_, rejectBody_);
+      httpSendJson(server, rejectCode_, body_);
       return;
     }
 
-    char body[96];
-
     if (parser_->failed()) {
-      snprintf(body, sizeof(body), "{\"ok\":false,\"error\":\"%s\"}", parser_->error());
-      httpSendJson(server, 415, body);
+      formatError(parser_->error());
+      httpSendJson(server, 415, body_);
       return;
     }
 
-    snprintf(body, sizeof(body), "{\"ok\":true,\"played_ms\":%lu}", static_cast<unsigned long>(playedMs()));
-    httpSendJson(server, 200, body);
+    snprintf(body_, sizeof(body_), "{\"ok\":true,\"played_ms\":%lu}", static_cast<unsigned long>(playedMs()));
+    httpSendJson(server, 200, body_);
   }
 
   void onPcm(const int16_t* samples, size_t count) override {
     writeMonoToSpeaker(samples, count);
-    updateAnimation();
+    samplesWritten_ += count;
+
+    if (player_) {
+      player_->advance(playedMs());
+      player_->update();
+    } else {
+      updateAnimation();
+    }
+
     updateRgb(millis());
   }
 
 private:
   std::optional<WavStreamParser> parser_;
+  std::optional<TimelinePlayer> player_;
   int rejectCode_ = 0;
-  const char* rejectBody_ = nullptr;
+  uint32_t samplesWritten_ = 0;
+  char error_[96] = {};
+  char body_[128] = {};
+
+  const char* acceptTimeline(const char* json, size_t length) {
+    std::optional<Timeline> timeline = Timeline::parse(json, length, TimelinePlayer::names(), error_, sizeof(error_));
+
+    if (!timeline) {
+      return error_;
+    }
 
-  void reject(int code, const char* body) {
+    player_.emplace(std::move(*timeline));
+    player_->advance(0);
+    return nullptr;
+  }
+
+  void reject(int code, const char* message) {
     rejectCode_ = code;
-    rejectBody_ = body;
+    formatError(message);
+  }
+
+  void formatError(const char* message) {
+    snprintf(body_, sizeof(body_), "{\"ok\":false,\"error\":\"%s\"}", message);
   }
 
   uint32_t playedMs() const {
-    return static_cast<uint32_t>(parser_->samplesDelivered() * 1000ULL / SAMPLE_RATE);
+    return static_cast<uint32_t>(samplesWritten_ * 1000ULL / SAMPLE_RATE);
   }
 };
 
diff --git a/test/test_timeline/test_timeline.cpp b/test/test_timeline/test_timeline.cpp
new file mode 100644
index 00000000..a036d727
--- /dev/null
+++ b/test/test_timeline/test_timeline.cpp
@@ -0,0 +1,101 @@
+#include <unity.h>
+
+#include <cstring>
+#include <string>
+
+#include "animation/timeline.h"
+
+namespace {
+
+const char* resolvePreset(const char* name, uint8_t& id) {
+  if (strcmp(name, "typing") == 0) {
+    id = 7;
+    return nullptr;
+  }
+  return strcmp(name, "ring") == 0 ? "plays its own audio" : "unknown";
+}
+
+const char* resolveEyes(const char* name, uint8_t& id) {
+  id = 3;
+  return strcmp(name, "thinking") == 0 ? nullptr : "unknown";
+}
+
+const Timeline::Names kNames = {resolvePreset, resolveEyes};
+
+char g_error[96];
+
+std::optional<Timeline> parse(const std::string& json) {
+  g_error[0] = '\0';
+  return Timeline::parse(json.data(), json.size(), kNames, g_error, sizeof(g_error));
+}
+
+}  // namespace
+
+void test_sleeps_set_start_times_and_moves_share_them() {
+  const auto timeline = parse(
+    R"([["preset","typing"],["sleep",500],["move","head",0.5,300],["move","neck",-0.5],["sleep",250],["eyes","thinking"]])"
+  );
+
+  TEST_ASSERT_TRUE(timeline.has_value());
+  const auto& steps = timeline->steps();
+  TEST_ASSERT_EQUAL_size_t(4, steps.size());
+  TEST_ASSERT_EQUAL_UINT32(0, steps[0].atMs);
+  TEST_ASSERT_EQUAL_UINT8(7, steps[0].target);
+  TEST_ASSERT_EQUAL_UINT32(500, steps[1].atMs);
+  TEST_ASSERT_EQUAL_UINT32(500, steps[2].atMs);
+  TEST_ASSERT_EQUAL_UINT32(750, steps[3].atMs);
+  TEST_ASSERT_TRUE(steps[3].kind == Timeline::Kind::Eyes);
+}
+
+void test_move_resolves_servo_and_clamps_position() {
+  const auto timeline = parse(R"([["move","HAND_RIGHT",3,200],["move","body",-0.25]])");
+
+  TEST_ASSERT_TRUE(timeline.has_value());
+  const auto& steps = timeline->steps();
+  TEST_ASSERT_EQUAL_UINT8(3, steps[0].target);
+  TEST_ASSERT_EQUAL_FLOAT(1.0f, steps[0].to);
+  TEST_ASSERT_EQUAL_UINT32(200, steps[0].durationMs);
+  TEST_ASSERT_EQUAL_UINT8(4, steps[1].target);
+  TEST_ASSERT_EQUAL_UINT32(0, steps[1].durationMs);
+}
+
+void test_resolver_reason_is_reported_with_step_index() {
+  TEST_ASSERT_FALSE(parse(R"([["sleep",10],["preset","ring"]])").has_value());
+  TEST_ASSERT_EQUAL_STRING("step 1: preset plays its own audio", g_error);
+}
+
+void test_rejects_malformed_steps() {
+  TEST_ASSERT_FALSE(parse(R"({"preset":"typing"})").has_value());
+  TEST_ASSERT_EQUAL_STRING("X-Anim is not a JSON array", g_error);
+
+  TEST_ASSERT_FALSE(parse(R"([["wiggle"]])").has_value());
+  TEST_ASSERT_EQUAL_STRING("step 0: unknown command", g_error);
+
+  TEST_ASSERT_FALSE(parse(R"([["move","tail",0.1]])").has_value());
+  TEST_ASSERT_EQUAL_STRING("step 0: unknown servo", g_error);
+
+  TEST_ASSERT_FALSE(parse(R"([["move","head"]])").has_value());
+  TEST_ASSERT_FALSE(parse(R"([["move","head",0.2,-5]])").has_value());
+  TEST_ASSERT_FALSE(parse(R"([["sleep",-1]])").has_value());
+  TEST_ASSERT_FALSE(parse(R"([["sleep",600001]])").has_value());
+}
+
+void test_rejects_too_many_steps() {
+  std::string json = "[";
+  for (size_t i = 0; i <= Timeline::kMaxSteps; i++) {
+    json += i == 0 ? "[\"sleep\",1]" : ",[\"sleep\",1]";
+  }
+  json += "]";
+
+  TEST_ASSERT_FALSE(parse(json).has_value());
+}
+
+int main(int, char**) {
+  UNITY_BEGIN();
+  RUN_TEST(test_sleeps_set_start_times_and_moves_share_them);
+  RUN_TEST(test_move_resolves_servo_and_clamps_position);
+  RUN_TEST(test_resolver_reason_is_reported_with_step_index);
+  RUN_TEST(test_rejects_malformed_steps);
+  RUN_TEST(test_rejects_too_many_steps);
+  return UNITY_END();
+}

From 054a19873fe8bad2ba135b85ee6391c7586f2818 Mon Sep 17 00:00:00 2001
From: shodan <mega@ioexception.at>
Date: Sat, 3 Oct 2026 23:15:35 +0200
Subject: [PATCH 03/21] feat(anim): script the eyes from the X-Anim timeline

New timeline steps:

  ["look", x, y, ms?]   move the gaze, -1..1 on each axis
  ["open", amount, ms?] lid opening, 0 closed to 1 normal
  ["blink"]             blink once
  ["face", name]        show an expression from the expressions library

look and open draw through the current eyes_style, so the kaomoji style
ignores them. A face replaces the eyes until the next look, open, eyes or
preset step; eyes and preset steps clear all scripted eye state.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 src/animation/timeline.cpp           | 146 ++++++++++++++++++---------
 src/animation/timeline.h             |  20 ++--
 src/animation/timeline_player.cpp    |  45 +++++++--
 src/display/eyes.h                   |   7 ++
 src/display/eyes/controller.cpp      |   8 +-
 src/display/eyes/script.cpp          | 119 ++++++++++++++++++++++
 src/display/eyes/script.h            |  15 +++
 src/display/eyes/styles/kaomoji.cpp  |  18 ++--
 src/display/eyes/styles/kaomoji.h    |   4 +
 test/test_timeline/test_timeline.cpp |  36 ++++++-
 10 files changed, 344 insertions(+), 74 deletions(-)
 create mode 100644 src/display/eyes/script.cpp
 create mode 100644 src/display/eyes/script.h

diff --git a/src/animation/timeline.cpp b/src/animation/timeline.cpp
index 28d98d91..99073fc1 100644
--- a/src/animation/timeline.cpp
+++ b/src/animation/timeline.cpp
@@ -21,6 +21,97 @@ bool findServo(const char* name, uint8_t& index) {
   return false;
 }
 
+float clampTo(float value, float lo, float hi) {
+  return value < lo ? lo : (value > hi ? hi : value);
+}
+
+bool isMs(JsonVariantConst value) {
+  return value.is<uint32_t>() && value.as<uint32_t>() <= Timeline::kMaxSleepMs;
+}
+
+bool isOptionalMs(JsonVariantConst value) {
+  return value.isNull() || isMs(value);
+}
+
+// Parses one step into `step`, or returns why it is invalid. Sleep only advances `atMs`.
+const char* parseStep(JsonArrayConst item, const Timeline::Names& names, uint32_t& atMs, std::optional<Timeline::Step>& step) {
+  using Kind = Timeline::Kind;
+
+  const char* command = item[0].as<const char*>();
+
+  if (command == nullptr) {
+    return "expected [command, ...]";
+  }
+
+  if (strcmp(command, "sleep") == 0) {
+    if (!isMs(item[1])) {
+      return "sleep needs 0..600000 ms";
+    }
+    atMs += item[1].as<uint32_t>();
+    return nullptr;
+  }
+
+  if (strcmp(command, "blink") == 0) {
+    step = Timeline::Step{atMs, Kind::Blink, 0, 0.0f, 0.0f, 0};
+    return nullptr;
+  }
+
+  if (strcmp(command, "preset") == 0 || strcmp(command, "eyes") == 0 || strcmp(command, "face") == 0) {
+    const Kind kind = command[0] == 'p' ? Kind::Preset : (command[0] == 'e' ? Kind::Eyes : Kind::Face);
+    const Timeline::NameResolver resolve = kind == Kind::Preset ? names.preset : (kind == Kind::Eyes ? names.eyes : names.face);
+    const char* name = item[1].as<const char*>();
+    uint8_t id = 0;
+
+    if (name == nullptr) {
+      return "needs a name";
+    }
+    if (const char* reason = resolve(name, id)) {
+      return reason;
+    }
+    step = Timeline::Step{atMs, kind, id, 0.0f, 0.0f, 0};
+    return nullptr;
+  }
+
+  if (strcmp(command, "move") == 0) {
+    const char* servo = item[1].as<const char*>();
+    uint8_t index = 0;
+
+    if (servo == nullptr || !findServo(servo, index)) {
+      return "unknown servo";
+    }
+    if (!item[2].is<float>() || !isOptionalMs(item[3])) {
+      return "move needs a position -1..1 and optional duration ms";
+    }
+    step = Timeline::Step{atMs, Kind::Move, index, servoSaturateNorm(item[2].as<float>()), 0.0f, item[3].as<uint32_t>()};
+    return nullptr;
+  }
+
+  if (strcmp(command, "look") == 0) {
+    if (!item[1].is<float>() || !item[2].is<float>() || !isOptionalMs(item[3])) {
+      return "look needs x and y -1..1 and optional duration ms";
+    }
+    step = Timeline::Step{
+      atMs,
+      Kind::Look,
+      0,
+      clampTo(item[1].as<float>(), -1.0f, 1.0f),
+      clampTo(item[2].as<float>(), -1.0f, 1.0f),
+      item[3].as<uint32_t>()
+    };
+    return nullptr;
+  }
+
+  if (strcmp(command, "open") == 0) {
+    if (!item[1].is<float>() || !isOptionalMs(item[2])) {
+      return "open needs an amount 0..1 and optional duration ms";
+    }
+    step = Timeline::Step{atMs, Kind::Open, 0, clampTo(item[1].as<float>(), 0.0f, 1.0f), 0.0f, item[2].as<uint32_t>()};
+    return nullptr;
+  }
+
+  return "unknown command";
+}
+
 }  // namespace
 
 std::optional<Timeline> Timeline::parse(
@@ -40,65 +131,24 @@ std::optional<Timeline> Timeline::parse(
   JsonArrayConst items = doc.as<JsonArrayConst>();
 
   if (items.size() > kMaxSteps) {
-    snprintf(error, errorSize, "anim has more than %u steps", static_cast<unsigned>(kMaxSteps));
+    snprintf(error, errorSize, "X-Anim has more than %u steps", static_cast<unsigned>(kMaxSteps));
     return std::nullopt;
   }
 
   Timeline timeline;
   uint32_t atMs = 0;
-  size_t index = 0;
+  unsigned index = 0;
 
   for (JsonArrayConst item : items) {
-    const char* command = item[0].as<const char*>();
+    std::optional<Step> step;
 
-    if (command == nullptr) {
-      snprintf(error, errorSize, "step %u: expected [command, ...]", static_cast<unsigned>(index));
+    if (const char* reason = parseStep(item, names, atMs, step)) {
+      snprintf(error, errorSize, "step %u: %s", index, reason);
       return std::nullopt;
     }
-
-    if (strcmp(command, "sleep") == 0) {
-      if (!item[1].is<uint32_t>() || item[1].as<uint32_t>() > kMaxSleepMs) {
-        snprintf(error, errorSize, "step %u: sleep needs 0..%lu ms", static_cast<unsigned>(index), static_cast<unsigned long>(kMaxSleepMs));
-        return std::nullopt;
-      }
-      atMs += item[1].as<uint32_t>();
-    } else if (strcmp(command, "preset") == 0 || strcmp(command, "eyes") == 0) {
-      const bool preset = command[0] == 'p';
-      const char* name = item[1].as<const char*>();
-      uint8_t id = 0;
-      const char* reason = name == nullptr ? "missing name" : (preset ? names.preset : names.eyes)(name, id);
-
-      if (reason != nullptr) {
-        snprintf(error, errorSize, "step %u: %s %s", static_cast<unsigned>(index), command, reason);
-        return std::nullopt;
-      }
-      timeline.steps_.push_back({atMs, preset ? Kind::Preset : Kind::Eyes, id, 0.0f, 0});
-    } else if (strcmp(command, "move") == 0) {
-      const char* servo = item[1].as<const char*>();
-      uint8_t servoIndex = 0;
-
-      if (servo == nullptr || !findServo(servo, servoIndex)) {
-        snprintf(error, errorSize, "step %u: unknown servo", static_cast<unsigned>(index));
-        return std::nullopt;
-      }
-      const bool hasDuration = !item[3].isNull();
-      if (!item[2].is<float>() || (hasDuration && (!item[3].is<uint32_t>() || item[3].as<uint32_t>() > kMaxSleepMs))) {
-        snprintf(error, errorSize, "step %u: move needs a position -1..1 and optional duration ms", static_cast<unsigned>(index));
-        return std::nullopt;
-      }
-
-      timeline.steps_.push_back({
-        atMs,
-        Kind::Move,
-        servoIndex,
-        servoSaturateNorm(item[2].as<float>()),
-        hasDuration ? item[3].as<uint32_t>() : 0
-      });
-    } else {
-      snprintf(error, errorSize, "step %u: unknown command", static_cast<unsigned>(index));
-      return std::nullopt;
+    if (step) {
+      timeline.steps_.push_back(*step);
     }
-
     index++;
   }
 
diff --git a/src/animation/timeline.h b/src/animation/timeline.h
index 980a358f..6b32286f 100644
--- a/src/animation/timeline.h
+++ b/src/animation/timeline.h
@@ -6,24 +6,31 @@
 #include <vector>
 
 // A choreography sent alongside streamed audio: a JSON array of steps such as
-// ["sleep", 500], ["preset", "typing"], ["move", "head", 0.6, 300], ["eyes", "thinking"].
+// ["sleep", 500], ["preset", "typing"], ["move", "head", 0.6, 300], ["look", -1, 0, 150].
 // Sleeps are folded into each step's start time, measured in playback milliseconds.
-// Moves do not block: moves without a sleep between them run together.
+// Steps do not block: steps without a sleep between them start together.
 class Timeline {
 public:
   enum class Kind : uint8_t {
     Preset,
     Move,
-    Eyes
+    Eyes,
+    Look,
+    Open,
+    Blink,
+    Face
   };
 
   struct Step {
     uint32_t atMs;
     Kind kind;
-    // Preset or eye-mode id from the resolver, or a servo index for Move.
+    // Preset, eye-mode or face id from a resolver, or a servo index for Move.
     uint8_t target;
-    float to;
-    // Time a Move should take to arrive; 0 moves at the maximum servo speed.
+    // Move position, look x or open amount.
+    float x;
+    // Look y.
+    float y;
+    // Time a Move, Look or Open takes to arrive; 0 is as fast as possible.
     uint32_t durationMs;
   };
 
@@ -33,6 +40,7 @@ class Timeline {
   struct Names {
     NameResolver preset;
     NameResolver eyes;
+    NameResolver face;
   };
 
   static constexpr size_t kMaxSteps = 256;
diff --git a/src/animation/timeline_player.cpp b/src/animation/timeline_player.cpp
index 98398fa9..70dfa54c 100644
--- a/src/animation/timeline_player.cpp
+++ b/src/animation/timeline_player.cpp
@@ -5,6 +5,8 @@
 #include <cmath>
 #include <cstring>
 
+#include <TinyEngineerExpressions.h>
+
 #include "animation/registry.h"
 #include "display/eyes.h"
 #include "hardware/servo_wrapper.h"
@@ -16,7 +18,7 @@ const char* resolvePreset(const char* name, uint8_t& id) {
   AnimationId anim;
 
   if (!parseAnimationName(name, anim)) {
-    return "unknown name";
+    return "unknown preset";
   }
 
   switch (anim) {
@@ -28,7 +30,7 @@ const char* resolvePreset(const char* name, uint8_t& id) {
       id = static_cast<uint8_t>(anim);
       return nullptr;
     default:
-      return "not available during playback";
+      return "preset not available during playback";
   }
 }
 
@@ -38,14 +40,29 @@ const char* resolveEyes(const char* name, uint8_t& id) {
   if (strcmp(name, "idle") == 0) {
     anim = AnimationId::None;
   } else if (!parseAnimationName(name, anim)) {
-    return "unknown name";
+    return "unknown eye mode";
   }
 
   id = static_cast<uint8_t>(modeByAnimId(anim)->eyeMode);
   return nullptr;
 }
 
-const Timeline::Names kNames = {resolvePreset, resolveEyes};
+const char* resolveFace(const char* name, uint8_t& id) {
+  namespace expressions = tiny_engineer::expressions;
+
+  for (uint8_t i = 0; i < expressions::kExpressionCount; i++) {
+    const char* candidate = expressions::name(static_cast<expressions::Expression>(i));
+
+    if (candidate != nullptr && strcmp(candidate, name) == 0) {
+      id = i;
+      return nullptr;
+    }
+  }
+
+  return "unknown face";
+}
+
+const Timeline::Names kNames = {resolvePreset, resolveEyes, resolveFace};
 
 }  // namespace
 
@@ -92,6 +109,22 @@ void TimelinePlayer::run(const Timeline::Step& step) {
       setEyeMode(static_cast<EyeMode>(step.target), millis());
       break;
 
+    case Timeline::Kind::Look:
+      eyesLookAt(step.x, step.y, step.durationMs, millis());
+      break;
+
+    case Timeline::Kind::Open:
+      eyesSetOpen(step.x, step.durationMs, millis());
+      break;
+
+    case Timeline::Kind::Blink:
+      eyesBlink(millis());
+      break;
+
+    case Timeline::Kind::Face:
+      eyesShowFace(step.target, millis());
+      break;
+
     case Timeline::Kind::Move: {
       manualServos_ = true;
       ensureAllServoOutputs();
@@ -100,11 +133,11 @@ void TimelinePlayer::run(const Timeline::Step& step) {
       float speed = SERVO_MAX_SPEED_DEG_S;
 
       if (step.durationMs > 0) {
-        const float distance = fabsf(servoNormToDeg(step.target, step.to) - servo.angle());
+        const float distance = fabsf(servoNormToDeg(step.target, step.x) - servo.angle());
         speed = fminf(SERVO_MAX_SPEED_DEG_S, fmaxf(1.0f, distance * 1000.0f / step.durationMs));
       }
 
-      servo.setNormTarget(step.to, speed);
+      servo.setNormTarget(step.x, speed);
       break;
     }
   }
diff --git a/src/display/eyes.h b/src/display/eyes.h
index b9a8139c..b063f903 100644
--- a/src/display/eyes.h
+++ b/src/display/eyes.h
@@ -40,7 +40,14 @@ void requestSleepEyeOpen(uint32_t now);
 void clearSleepEyeAnim();
 SleepEyeResult updateSleepEyes(uint32_t now);
 
+// Also clears the scripted overrides below.
 void setEyeMode(EyeMode mode, uint32_t now);
+
+// Scripted overrides for POST /play timelines. x/y and amount are -1..1 and 0..1.
+void eyesLookAt(float x, float y, uint32_t durationMs, uint32_t now);
+void eyesSetOpen(float amount, uint32_t durationMs, uint32_t now);
+void eyesBlink(uint32_t now);
+void eyesShowFace(uint8_t expression, uint32_t now);
 void triggerEyeImpact(uint32_t now);
 
 const Eye& leftEye();
diff --git a/src/display/eyes/controller.cpp b/src/display/eyes/controller.cpp
index 09eb3882..31ea4561 100644
--- a/src/display/eyes/controller.cpp
+++ b/src/display/eyes/controller.cpp
@@ -14,6 +14,7 @@
 #include "display/eyes/core/impact.h"
 #include "display/eyes/core/internal.h"
 #include "display/eyes/core/util.h"
+#include "display/eyes/script.h"
 #include "display/eyes/styles/eye_style.h"
 #include "display/eyes/styles/kaomoji.h"
 #include "settings/settings.h"
@@ -58,7 +59,7 @@ EyeStyleSleepPhase currentSleepPhase() {
 void updateModePose(uint32_t now) {
   const ModeEntry* entry = modeByEyeMode(g_eyeMode);
 
-  if (entry->updateEyes != nullptr) {
+  if (!eyes::applyScriptPose(g_leftEye, g_rightEye, now) && entry->updateEyes != nullptr) {
     entry->updateEyes(now);
   }
 
@@ -66,6 +67,10 @@ void updateModePose(uint32_t now) {
 }
 
 void drawCurrentEyes(uint32_t now) {
+  if (eyes::drawScriptFace(now)) {
+    return;
+  }
+
   const EyeStyleRenderer* style = currentEyeStyle();
   style->draw(
     g_eyeMode,
@@ -180,6 +185,7 @@ void setEyesRunning(bool active) {
 }  // namespace eyes
 
 void setEyeMode(EyeMode mode, uint32_t now) {
+  eyes::clearScript();
   g_eyeMode = mode;
   g_modeStartedMs = now;
   resetImpactState();
diff --git a/src/display/eyes/script.cpp b/src/display/eyes/script.cpp
new file mode 100644
index 00000000..03681e5e
--- /dev/null
+++ b/src/display/eyes/script.cpp
@@ -0,0 +1,119 @@
+#include "display/eyes/script.h"
+
+#include "animation/util.h"
+#include "display/eyes/core/blink.h"
+#include "display/eyes/core/constants.h"
+#include "display/eyes/core/internal.h"
+#include "display/eyes/core/util.h"
+#include "display/eyes/styles/kaomoji.h"
+
+namespace {
+
+namespace expressions = tiny_engineer::expressions;
+
+// Gaze offset at -1 or +1, in pixels; keeps both eyes on the 128x32 panel.
+constexpr float kLookRangeX = 16.0f;
+constexpr float kLookRangeY = 8.0f;
+
+struct Tween {
+  float from;
+  float to;
+  uint32_t startMs;
+  uint32_t durationMs;
+
+  float at(uint32_t now) const {
+    const float t = anim::easeInOutCubic(eyes::moveProgress(now, startMs, durationMs));
+    return from + (to - from) * t;
+  }
+
+  void retarget(float target, uint32_t durationMs_, uint32_t now) {
+    from = at(now);
+    to = target;
+    startMs = now;
+    durationMs = durationMs_;
+  }
+};
+
+bool g_posing = false;
+Tween g_lookX = {0.0f, 0.0f, 0, 0};
+Tween g_lookY = {0.0f, 0.0f, 0, 0};
+Tween g_open = {1.0f, 1.0f, 0, 0};
+
+bool g_faceShowing = false;
+expressions::Expression g_face = expressions::Expression::Idle;
+uint32_t g_faceStartedMs = 0;
+
+Eye scriptedEye(const Eye& base, uint32_t now) {
+  const int16_t height = static_cast<int16_t>(base.height * g_open.at(now));
+
+  return {
+    static_cast<int16_t>(base.x + g_lookX.at(now) * kLookRangeX),
+    static_cast<int16_t>(base.y + g_lookY.at(now) * kLookRangeY + (base.height - height) / 2),
+    base.width,
+    height
+  };
+}
+
+void beginPosing() {
+  if (!g_posing) {
+    g_lookX = {0.0f, 0.0f, 0, 0};
+    g_lookY = {0.0f, 0.0f, 0, 0};
+    g_open = {1.0f, 1.0f, 0, 0};
+    g_posing = true;
+  }
+
+  g_faceShowing = false;
+  eyes::requestForceRedraw();
+}
+
+}  // namespace
+
+void eyesLookAt(float x, float y, uint32_t durationMs, uint32_t now) {
+  beginPosing();
+  g_lookX.retarget(x, durationMs, now);
+  g_lookY.retarget(y, durationMs, now);
+}
+
+void eyesSetOpen(float amount, uint32_t durationMs, uint32_t now) {
+  beginPosing();
+  g_open.retarget(amount, durationMs, now);
+}
+
+void eyesBlink(uint32_t now) {
+  blinkScheduleSoon(now, 0, 0);
+}
+
+void eyesShowFace(uint8_t expression, uint32_t now) {
+  g_face = static_cast<expressions::Expression>(expression);
+  g_faceStartedMs = now;
+  g_faceShowing = true;
+  eyes::requestForceRedraw();
+}
+
+namespace eyes {
+
+bool applyScriptPose(Eye& left, Eye& right, uint32_t now) {
+  if (!g_posing) {
+    return false;
+  }
+
+  left = scriptedEye(DEFAULT_LEFT, now);
+  right = scriptedEye(DEFAULT_RIGHT, now);
+  return true;
+}
+
+bool drawScriptFace(uint32_t now) {
+  if (!g_faceShowing) {
+    return false;
+  }
+
+  drawKaomojiFrame(g_face, now - g_faceStartedMs);
+  return true;
+}
+
+void clearScript() {
+  g_posing = false;
+  g_faceShowing = false;
+}
+
+}  // namespace eyes
diff --git a/src/display/eyes/script.h b/src/display/eyes/script.h
new file mode 100644
index 00000000..5fda41ff
--- /dev/null
+++ b/src/display/eyes/script.h
@@ -0,0 +1,15 @@
+#pragma once
+
+#include <cstdint>
+
+#include "display/eyes.h"
+
+namespace eyes {
+
+// Overwrites the eye rects when a scripted look or open is active.
+bool applyScriptPose(Eye& left, Eye& right, uint32_t now);
+// Draws the scripted face, if one is showing.
+bool drawScriptFace(uint32_t now);
+void clearScript();
+
+}  // namespace eyes
diff --git a/src/display/eyes/styles/kaomoji.cpp b/src/display/eyes/styles/kaomoji.cpp
index 029163c7..5c176f7d 100644
--- a/src/display/eyes/styles/kaomoji.cpp
+++ b/src/display/eyes/styles/kaomoji.cpp
@@ -74,14 +74,14 @@ void drawKaomoji(
     g_expressionArmed = true;
   }
 
-  const uint32_t elapsed = now - g_expressionStartedMs;
-
-  if (!expressions::render(
-        expression,
-        elapsed,
-        g_kaomojiFrame,
-        sizeof(g_kaomojiFrame)
-      )) {
+  drawKaomojiFrame(expression, now - g_expressionStartedMs);
+}
+
+}  // namespace
+
+void drawKaomojiFrame(tiny_engineer::expressions::Expression expression, uint32_t elapsedMs) {
+  if (!oledAvailable ||
+      !expressions::render(expression, elapsedMs, g_kaomojiFrame, sizeof(g_kaomojiFrame))) {
     return;
   }
 
@@ -97,8 +97,6 @@ void drawKaomoji(
   display.display();
 }
 
-}  // namespace
-
 void kaomojiResetPlayback(uint32_t now) {
   g_expressionArmed = false;
   g_expressionStartedMs = now;
diff --git a/src/display/eyes/styles/kaomoji.h b/src/display/eyes/styles/kaomoji.h
index 51046ecb..47a61d8a 100644
--- a/src/display/eyes/styles/kaomoji.h
+++ b/src/display/eyes/styles/kaomoji.h
@@ -2,5 +2,9 @@
 
 #include <cstdint>
 
+#include <TinyEngineerExpressions.h>
+
 // Reset kaomoji face playback so the next draw starts at frame 0.
 void kaomojiResetPlayback(uint32_t now);
+
+void drawKaomojiFrame(tiny_engineer::expressions::Expression expression, uint32_t elapsedMs);
diff --git a/test/test_timeline/test_timeline.cpp b/test/test_timeline/test_timeline.cpp
index a036d727..4fc6aab4 100644
--- a/test/test_timeline/test_timeline.cpp
+++ b/test/test_timeline/test_timeline.cpp
@@ -12,7 +12,7 @@ const char* resolvePreset(const char* name, uint8_t& id) {
     id = 7;
     return nullptr;
   }
-  return strcmp(name, "ring") == 0 ? "plays its own audio" : "unknown";
+  return strcmp(name, "ring") == 0 ? "preset plays its own audio" : "unknown preset";
 }
 
 const char* resolveEyes(const char* name, uint8_t& id) {
@@ -20,7 +20,12 @@ const char* resolveEyes(const char* name, uint8_t& id) {
   return strcmp(name, "thinking") == 0 ? nullptr : "unknown";
 }
 
-const Timeline::Names kNames = {resolvePreset, resolveEyes};
+const char* resolveFace(const char* name, uint8_t& id) {
+  id = 9;
+  return strcmp(name, "love") == 0 ? nullptr : "unknown face";
+}
+
+const Timeline::Names kNames = {resolvePreset, resolveEyes, resolveFace};
 
 char g_error[96];
 
@@ -53,12 +58,36 @@ void test_move_resolves_servo_and_clamps_position() {
   TEST_ASSERT_TRUE(timeline.has_value());
   const auto& steps = timeline->steps();
   TEST_ASSERT_EQUAL_UINT8(3, steps[0].target);
-  TEST_ASSERT_EQUAL_FLOAT(1.0f, steps[0].to);
+  TEST_ASSERT_EQUAL_FLOAT(1.0f, steps[0].x);
   TEST_ASSERT_EQUAL_UINT32(200, steps[0].durationMs);
   TEST_ASSERT_EQUAL_UINT8(4, steps[1].target);
   TEST_ASSERT_EQUAL_UINT32(0, steps[1].durationMs);
 }
 
+void test_eye_steps() {
+  const auto timeline = parse(R"([["look",-2,0.5,150],["open",0.3],["sleep",100],["blink"],["face","love"]])");
+
+  TEST_ASSERT_TRUE(timeline.has_value());
+  const auto& steps = timeline->steps();
+  TEST_ASSERT_EQUAL_size_t(4, steps.size());
+  TEST_ASSERT_TRUE(steps[0].kind == Timeline::Kind::Look);
+  TEST_ASSERT_EQUAL_FLOAT(-1.0f, steps[0].x);
+  TEST_ASSERT_EQUAL_FLOAT(0.5f, steps[0].y);
+  TEST_ASSERT_EQUAL_UINT32(150, steps[0].durationMs);
+  TEST_ASSERT_TRUE(steps[1].kind == Timeline::Kind::Open);
+  TEST_ASSERT_EQUAL_FLOAT(0.3f, steps[1].x);
+  TEST_ASSERT_EQUAL_UINT32(0, steps[1].durationMs);
+  TEST_ASSERT_TRUE(steps[2].kind == Timeline::Kind::Blink);
+  TEST_ASSERT_EQUAL_UINT32(100, steps[2].atMs);
+  TEST_ASSERT_TRUE(steps[3].kind == Timeline::Kind::Face);
+  TEST_ASSERT_EQUAL_UINT8(9, steps[3].target);
+
+  TEST_ASSERT_FALSE(parse(R"([["look",0.5]])").has_value());
+  TEST_ASSERT_FALSE(parse(R"([["open","wide"]])").has_value());
+  TEST_ASSERT_FALSE(parse(R"([["face","grumpy"]])").has_value());
+  TEST_ASSERT_EQUAL_STRING("step 0: unknown face", g_error);
+}
+
 void test_resolver_reason_is_reported_with_step_index() {
   TEST_ASSERT_FALSE(parse(R"([["sleep",10],["preset","ring"]])").has_value());
   TEST_ASSERT_EQUAL_STRING("step 1: preset plays its own audio", g_error);
@@ -94,6 +123,7 @@ int main(int, char**) {
   UNITY_BEGIN();
   RUN_TEST(test_sleeps_set_start_times_and_moves_share_them);
   RUN_TEST(test_move_resolves_servo_and_clamps_position);
+  RUN_TEST(test_eye_steps);
   RUN_TEST(test_resolver_reason_is_reported_with_step_index);
   RUN_TEST(test_rejects_malformed_steps);
   RUN_TEST(test_rejects_too_many_steps);

From 698c89c22bf91b72e48d3ee7cc57decc1551d6bb Mon Sep 17 00:00:00 2001
From: shodan <mega@ioexception.at>
Date: Sun, 4 Oct 2026 10:26:43 +0200
Subject: [PATCH 04/21] feat(integrations): add a play command for agent-driven
 animations

`tiny-engineer-claude-code play clip.wav --anim '[...]'` streams a WAV to
POST /play with the timeline in X-Anim. Unlike hook mode it reports back:
the robot's reply on stdout, the reason on stderr and exit code 1 on any
failure, so an agent can correct its timeline. --anim-file reads the
timeline from a file and is squashed onto one header line.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VYDrnWNM6nbcQ1nx8aua93
---
 docs/integration.md                           | 11 +++
 packages/tiny-engineer-claude-code/src/cli.js | 61 ++++++++++++++++
 .../tiny-engineer-claude-code/src/play.js     | 72 +++++++++++++++++++
 .../test/play.test.js                         | 60 ++++++++++++++++
 4 files changed, 204 insertions(+)
 create mode 100644 packages/tiny-engineer-claude-code/src/play.js
 create mode 100644 packages/tiny-engineer-claude-code/test/play.test.js

diff --git a/docs/integration.md b/docs/integration.md
index 28693fd8..dcb7d760 100644
--- a/docs/integration.md
+++ b/docs/integration.md
@@ -238,6 +238,17 @@ Inside this firmware repository, [`.claude/settings.json`](../.claude/settings.j
 
 To use it in every project, copy the `hooks` block into `~/.claude/settings.json` and replace `$CLAUDE_PROJECT_DIR/packages/…` with the absolute path to this repo's bin.
 
+### Custom animations from the agent
+
+The same CLI has a `play` command that an agent can run to speak and move. It streams a WAV to [`POST /play`](api.md#post-play) with a timeline of moves, gaze and faces, prints the robot's reply when the clip ends, and exits 1 with the reason on any error:
+
+```bash
+node packages/tiny-engineer-claude-code/bin/tiny-engineer-claude-code.js play hello.wav \
+  --anim '[["preset","thinking"],["sleep",800],["move","head",0.6,300],["face","happy"]]'
+```
+
+`--anim-file dance.json` reads the timeline from a file. `--help` lists every step.
+
 ### Smoke test
 
 ```bash
diff --git a/packages/tiny-engineer-claude-code/src/cli.js b/packages/tiny-engineer-claude-code/src/cli.js
index dcf98c94..eddc6958 100644
--- a/packages/tiny-engineer-claude-code/src/cli.js
+++ b/packages/tiny-engineer-claude-code/src/cli.js
@@ -1,9 +1,13 @@
+import { readFileSync } from "node:fs";
+
 import { DEFAULT_URL, getBaseUrl, getToken, loadDotEnv } from "./env.js";
 import { animationForEvent } from "./map.js";
+import { parsePlayArgs, postPlay } from "./play.js";
 import { postAnim } from "./post.js";
 
 function printHelp() {
   console.log(`Usage: tiny-engineer-claude-code [options]
+       tiny-engineer-claude-code play <clip.wav> [--anim <json> | --anim-file <path>] [--url <base>]
 
 Claude Code hook helper: read event JSON from stdin, pick an animation, POST to the robot.
 
@@ -44,7 +48,24 @@ Event map:
   Stop                                             → ring
   StopFailure                                      → error
 
+Play mode:
+  Streams a 16-bit mono PCM WAV (at the robot's sample rate) to POST /play and
+  runs an optional timeline alongside it. Steps run in order; only "sleep"
+  advances time, so steps without a sleep between them start together:
+    ["sleep", ms]                 wait ms of playback
+    ["preset", name]              none, typing, reading, thinking or wakeup
+    ["move", servo, to, ms?]      head, neck, hand_left, hand_right or body to -1..1
+    ["eyes", mode]                idle, thinking, error, ... (an /anim name)
+    ["look", x, y, ms?]           gaze: x -1 screen left..1 right, y -1 up..1 down
+    ["open", amount, ms?]         eyelids, 0 closed to 1 open
+    ["blink"]
+    ["face", name]                idle, happy, laugh, wink, curious, thinking,
+                                  surprise, smug, sleepy, sleep, sad, cry, angry,
+                                  panic, shy or love
+  Prints the robot's JSON reply when the clip ends; exits 1 on any error.
+
 Examples:
+  tiny-engineer-claude-code play hello.wav --anim '[["preset","thinking"],["sleep",800],["move","head",0.6,300],["face","happy"]]'
   echo '{"hook_event_name":"Stop"}' | tiny-engineer-claude-code
   echo '{"hook_event_name":"PreToolUse","tool_name":"Read"}' | tiny-engineer-claude-code --url http://192.168.1.10
 `);
@@ -95,12 +116,52 @@ function readStdin() {
   });
 }
 
+/**
+ * @param {string[]} argv arguments after `play`
+ */
+async function runPlay(argv) {
+  const opts = parsePlayArgs(argv);
+  if (opts.error) {
+    console.error(opts.error);
+    process.exitCode = 1;
+    return;
+  }
+
+  let wav;
+  try {
+    wav = readFileSync(opts.wavPath);
+  } catch (err) {
+    console.error(`cannot read ${opts.wavPath}: ${err.message}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  try {
+    const reply = await postPlay({
+      baseUrl: opts.url ?? getBaseUrl(),
+      wav,
+      anim: opts.anim,
+      token: getToken(),
+    });
+    (reply.ok ? console.log : console.error)(reply.body);
+    process.exitCode = reply.ok ? 0 : 1;
+  } catch (err) {
+    console.error(`robot unreachable: ${err.cause?.message ?? err.message}`);
+    process.exitCode = 1;
+  }
+}
+
 /**
  * @param {string[]} argv
  */
 export async function run(argv) {
   loadDotEnv();
 
+  if (argv[0] === "play") {
+    await runPlay(argv.slice(1));
+    return;
+  }
+
   const opts = parseArgs(argv);
   if (opts.error) {
     console.error(opts.error);
diff --git a/packages/tiny-engineer-claude-code/src/play.js b/packages/tiny-engineer-claude-code/src/play.js
new file mode 100644
index 00000000..269a3b02
--- /dev/null
+++ b/packages/tiny-engineer-claude-code/src/play.js
@@ -0,0 +1,72 @@
+import { readFileSync } from "node:fs";
+
+// The robot answers once the clip has finished playing.
+const PLAY_TIMEOUT_MS = 10 * 60 * 1000;
+
+/**
+ * @param {string[]} argv arguments after `play`
+ * @returns {{ wavPath?: string, anim?: string, url?: string, error?: string }}
+ */
+export function parsePlayArgs(argv) {
+  /** @type {{ wavPath?: string, anim?: string, url?: string }} */
+  const opts = {};
+  let animSource;
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    const value = argv[i + 1];
+
+    if (arg === "--anim" || arg === "--anim-file" || arg === "--url") {
+      if (!value) return { error: `${arg} requires a value` };
+      i++;
+      if (arg === "--url") {
+        opts.url = value;
+        continue;
+      }
+      if (animSource) return { error: "use --anim or --anim-file, not both" };
+      animSource = arg;
+      try {
+        opts.anim = arg === "--anim" ? value : readFileSync(value, "utf8");
+      } catch (err) {
+        return { error: `cannot read ${value}: ${err.message}` };
+      }
+      continue;
+    }
+    if (arg.startsWith("-") || opts.wavPath) return { error: `Unknown argument: ${arg}` };
+    opts.wavPath = arg;
+  }
+
+  if (!opts.wavPath) return { error: "play needs a WAV file" };
+
+  if (opts.anim !== undefined) {
+    try {
+      // One header line: drop the whitespace a file or pretty-printed JSON carries.
+      opts.anim = JSON.stringify(JSON.parse(opts.anim));
+    } catch {
+      return { error: "the timeline is not valid JSON" };
+    }
+  }
+
+  return opts;
+}
+
+/**
+ * POST a WAV to /play, with the timeline in X-Anim. Resolves with the robot's reply.
+ * @param {{ baseUrl: string, wav: Uint8Array, anim?: string, token?: string | null }} request
+ * @returns {Promise<{ ok: boolean, status: number, body: string }>}
+ */
+export async function postPlay({ baseUrl, wav, anim, token }) {
+  /** @type {Record<string, string>} */
+  const headers = { "Content-Type": "audio/wav" };
+  if (anim) headers["X-Anim"] = anim;
+  if (token) headers.Authorization = `Bearer ${token}`;
+
+  const response = await fetch(`${baseUrl.replace(/\/+$/, "")}/play`, {
+    method: "POST",
+    headers,
+    body: wav,
+    signal: AbortSignal.timeout(PLAY_TIMEOUT_MS),
+  });
+
+  return { ok: response.ok, status: response.status, body: await response.text() };
+}
diff --git a/packages/tiny-engineer-claude-code/test/play.test.js b/packages/tiny-engineer-claude-code/test/play.test.js
new file mode 100644
index 00000000..2e8f6931
--- /dev/null
+++ b/packages/tiny-engineer-claude-code/test/play.test.js
@@ -0,0 +1,60 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { createServer } from "node:http";
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { parsePlayArgs, postPlay } from "../src/play.js";
+
+test("a timeline file is squashed onto one header line", () => {
+  const dir = mkdtempSync(join(tmpdir(), "te-claude-code-play-"));
+  const file = join(dir, "dance.json");
+  writeFileSync(file, '[\n  ["preset", "typing"],\n  ["sleep", 500]\n]\n');
+
+  assert.deepEqual(parsePlayArgs(["clip.wav", "--anim-file", file]), {
+    wavPath: "clip.wav",
+    anim: '[["preset","typing"],["sleep",500]]',
+  });
+});
+
+test("play rejects bad arguments before contacting the robot", () => {
+  assert.equal(parsePlayArgs(["--anim", "[]"]).error, "play needs a WAV file");
+  assert.equal(parsePlayArgs(["clip.wav", "--anim", "[[\"sleep\""]).error, "the timeline is not valid JSON");
+  assert.equal(
+    parsePlayArgs(["clip.wav", "--anim", "[]", "--anim-file", "x.json"]).error,
+    "use --anim or --anim-file, not both",
+  );
+  assert.equal(parsePlayArgs(["a.wav", "b.wav"]).error, "Unknown argument: b.wav");
+});
+
+test("postPlay streams the WAV with the timeline and token headers", async () => {
+  let received;
+  const server = createServer((req, res) => {
+    const chunks = [];
+    req.on("data", (chunk) => chunks.push(chunk));
+    req.on("end", () => {
+      received = { url: req.url, headers: req.headers, body: Buffer.concat(chunks) };
+      res.writeHead(200, { "Content-Type": "application/json" });
+      res.end('{"ok":true,"played_ms":10}');
+    });
+  });
+  await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
+  const { port } = server.address();
+
+  try {
+    const reply = await postPlay({
+      baseUrl: `http://127.0.0.1:${port}/`,
+      wav: Buffer.from("RIFFdata"),
+      anim: '[["blink"]]',
+      token: "secret",
+    });
+
+    assert.deepEqual(reply, { ok: true, status: 200, body: '{"ok":true,"played_ms":10}' });
+    assert.equal(received.url, "/play");
+    assert.equal(received.headers["x-anim"], '[["blink"]]');
+    assert.equal(received.headers.authorization, "Bearer secret");
+    assert.equal(received.body.toString(), "RIFFdata");
+  } finally {
+    server.close();
+  }
+});

From 4f31b0834369e780bab8e5eefdfb898f562eacd7 Mon Sep 17 00:00:00 2001
From: shodan <mega@ioexception.at>
Date: Sun, 4 Oct 2026 10:26:43 +0200
Subject: [PATCH 05/21] docs(http): document POST /play and its X-Anim timeline

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VYDrnWNM6nbcQ1nx8aua93
---
 README.md                |  2 +-
 docs/api.md              | 58 +++++++++++++++++++++++++++++++++++++---
 docs/hardware/testing.md |  1 +
 src/http/index_page.cpp  | 13 +++++++++
 4 files changed, 70 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index a787452c..18e1bab1 100644
--- a/README.md
+++ b/README.md
@@ -14,7 +14,7 @@
 **Works with**
 
 - **Ready integrations:** [Claude Code](docs/integration.md#4-claude-code-dedicated-script) · [Cursor](docs/hooks.md) · [Antigravity](docs/integration.md#3-antigravity-cli-dedicated-script)
-- **Any agent with HTTP:** Codex, Windsurf, custom scripts, `POST /anim` on your LAN ([integration guide](docs/integration.md))
+- **Any agent with HTTP:** Codex, Windsurf, custom scripts, `POST /anim` on your LAN ([integration guide](docs/integration.md)), or `POST /play` to stream speech with custom moves, gaze and faces ([HTTP API](docs/api.md#post-play))
 
 ## What it feels like
 
diff --git a/docs/api.md b/docs/api.md
index 3b0cae8d..f690cf9a 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -536,14 +536,64 @@ Wrong params return **400**:
 | `missing name` | Query param `name` absent |
 | `unknown animation` | `name` not `none`, `typing`, `reading`, `thinking`, `ring`, `welcome`, `attention`, `error`, `abort`, `dead`, `wakeup`, or `sleep` |
 
+### `POST /play`
+
+Streams a WAV to the speaker and optionally drives the robot from a timeline while it plays. The body is played as it arrives, so clips of any length need no storage on the robot. The response comes when the clip ends.
+
+| Part | Value |
+| --- | --- |
+| Body | WAV, 16-bit mono PCM at 44100 Hz (the firmware `SAMPLE_RATE`). `Content-Length` is required. Chunks other than `fmt ` and `data` are skipped |
+| `X-Anim` header | Optional JSON array of timeline steps, up to 8 KB and 256 steps |
+| `Authorization` | `Bearer <token>` when `access_token` is set |
+
+Timeline steps run in order. Only `sleep` advances the clock, so steps without a `sleep` between them start together. The clock is the audio playback position: if the network stalls, the timeline waits with the audio.
+
+| Step | Effect |
+| --- | --- |
+| `["sleep", ms]` | Wait `ms` (0–600000) of playback |
+| `["preset", name]` | Run an animation without its sound: `none`, `typing`, `reading`, `thinking`, or `wakeup`. Drives all joints and the eyes |
+| `["move", servo, to, ms?]` | Move `head`, `neck`, `hand_left`, `hand_right`, or `body` to pose position `to` (−1 = saved min, 1 = saved max) so it arrives after `ms`. Without `ms` it moves at the maximum speed (140°/s), which also caps short durations. Stops the running preset; other joints hold where they are |
+| `["eyes", mode]` | Switch the eye mode: `idle` or any `/anim` name |
+| `["look", x, y, ms?]` | Gaze offset reached after `ms`: `x` −1 screen left to 1 screen right, `y` −1 up to 1 down |
+| `["open", amount, ms?]` | Lid opening, 0 closed to 1 normal, reached after `ms` |
+| `["blink"]` | One blink |
+| `["face", name]` | Animated face from the expression library: `idle`, `happy`, `laugh`, `wink`, `curious`, `thinking`, `surprise`, `smug`, `sleepy`, `sleep`, `sad`, `cry`, `angry`, `panic`, `shy`, or `love` |
+
+`look` and `open` reshape the eyes in the current `eyes_style`; `kaomoji` ignores them. A `face` replaces the eyes until the next `look`, `open`, `eyes`, or `preset` step. `eyes` and `preset` clear all scripted eye state.
+
+When the clip ends, steps that have not run are dropped. The robot returns to the continuous animation (`typing`, `reading`, `thinking`) that was running before the request, otherwise to `none`.
+
+```bash
+curl -X POST http://tiny-engineer.local/play \
+  -H 'Content-Type: audio/wav' \
+  -H 'X-Anim: [["preset","thinking"],["sleep",800],["move","head",0.6,300],["move","neck",-0.3,300],["face","happy"],["sleep",1200],["look",-1,0,150]]' \
+  --data-binary @clip.wav
+```
+
+```json
+{ "ok": true, "played_ms": 3000 }
+```
+
+The Claude Code CLI wraps this for agents: `tiny-engineer-claude-code play clip.wav --anim '[...]'` ([integration.md](integration.md#4-claude-code-dedicated-script)).
+
+Errors arrive before any audio plays:
+
+| Status | `error` | When |
+| --- | --- | --- |
+| `400` | `step N: ...` | Timeline step `N` (0-based) is invalid, names an unknown servo, eye mode or face, or a preset that plays its own sound |
+| `400` | `X-Anim is not a JSON array` | Header is not a JSON array |
+| `415` | `expected 16-bit mono PCM at 44100 Hz` | WAV format or sample rate differs |
+| `415` | `not a WAV file`, `no audio data` | Body is not a RIFF/WAVE file, or has no `data` chunk |
+
 ## Errors
 
 | Status | Body | When |
 | --- | --- | --- |
-| `400` | `{"ok":false,"error":"..."}` | Bad `/test/servo`, `/setup/servo`, `/setup/led`, `/setup/audio`, `/setup/oled`, or `/anim` params (see tables above) |
+| `400` | `{"ok":false,"error":"..."}` | Bad `/test/servo`, `/setup/servo`, `/setup/led`, `/setup/audio`, `/setup/oled`, or `/anim` params, or a bad `/play` timeline (see tables above) |
 | `401` | `{"ok":false,"error":"unauthorized"}` | Access token configured and `Authorization: Bearer` missing or wrong |
 | `404` | `{"ok":false,"error":"not found"}` | Unknown path |
-| `405` | `{"ok":false,"error":"method not allowed"}` | Wrong method on a `/test/*`, `/setup/servo`, `/setup/led`, `/setup/audio`, `/setup/oled`, `/settings`, `/settings/reset`, `/anim`, or `/auth` path |
+| `415` | `{"ok":false,"error":"..."}` | `/play` body is not a supported WAV |
+| `405` | `{"ok":false,"error":"method not allowed"}` | Wrong method on a `/test/*`, `/setup/servo`, `/setup/led`, `/setup/audio`, `/setup/oled`, `/settings`, `/settings/reset`, `/anim`, `/play`, or `/auth` path |
 
 Test routes are **POST**. GET/prefetch would move hardware. `/anim` allows **GET** (read) and **POST** (set). `/auth` is **GET** only and always public.
 
@@ -555,7 +605,9 @@ Test handlers **block** until the test finishes. The client waits. After each te
 
 The onboard RGB LED follows the active animation (see [RGB LED](#rgb-led)).
 
-One request at a time — the Arduino `WebServer` is single-threaded.
+`/play` holds the connection until the clip ends.
+
+One request at a time — the Arduino `WebServer` is single-threaded. While `/play` streams, other requests wait.
 
 ## RGB LED
 
diff --git a/docs/hardware/testing.md b/docs/hardware/testing.md
index 138a05c6..70f1246a 100644
--- a/docs/hardware/testing.md
+++ b/docs/hardware/testing.md
@@ -109,6 +109,7 @@ curl -X POST "http://tiny-engineer.local/test/servo?index=0&angle=90"
 | `GET` | `/auth` | Auth status (`ok`, `required`, `wifi_configured`, `provisioning`) — always public |
 | `GET` | `/health` | Health JSON — full field list in [api.md](../api.md#get-health) |
 | `GET` / `POST` | `/anim` | Current animation / start one (`name`, optional `interrupt`) — full params in [api.md](../api.md#post-anim) |
+| `POST` | `/play` | Stream a WAV with an optional `X-Anim` timeline; answers when the clip ends — full params in [api.md](../api.md#post-play) |
 | `GET` | `/settings` | Persistent settings (`sleep_timeout`, `hostname`, `volume`, `welcome`, `serial_log`, `continuous_timeout`, `loading`, `eyes_style`, `access_token_set`, `wifi_configured`, `wifi_ssid`, `wifi_password_set`, `servo_mins`, `servo_maxs`, `rgb_order`, `oled_rotate_180`) |
 | `POST` | `/settings?...&wifi_ssid=&wifi_password=` | Update NVS settings; WiFi params setup-AP-only and tested before save; `reboot_required` if hostname changed |
 | `POST` | `/settings?...&servo_mins=&servo_maxs=` | Servo min/max comma lists; setup-AP-only |
diff --git a/src/http/index_page.cpp b/src/http/index_page.cpp
index 8d7fe53c..bae44a78 100644
--- a/src/http/index_page.cpp
+++ b/src/http/index_page.cpp
@@ -237,6 +237,7 @@ body:not(.setup-mode) #setup-wizard{display:none!important}
 <tr><td>POST</td><td><code>/settings/reset</code></td><td>Factory reset all settings to defaults</td></tr>
 <tr><td>GET</td><td><code>/anim</code></td><td>Current animation name</td></tr>
 <tr><td>POST</td><td><code>/anim</code></td><td>Set animation (see parameters below)</td></tr>
+<tr><td>POST</td><td><code>/play</code></td><td>Stream a WAV with an optional animation timeline (see parameters below)</td></tr>
 <tr><td>POST</td><td><code>/test/audio</code></td><td>Play tone test</td></tr>
 <tr><td>POST</td><td><code>/test/audio/bell</code></td><td>Play bell WAV from LittleFS</td></tr>
 <tr><td>POST</td><td><code>/test/screen</code></td><td>OLED demo</td></tr>
@@ -284,6 +285,18 @@ body:not(.setup-mode) #setup-wizard{display:none!important}
 <tr><td><code>wakeup</code></td><td>One-shot sleep-inertia wake</td></tr>
 <tr><td><code>sleep</code></td><td>Close eyes and sleep</td></tr>
 </table>
+<p>POST <code>/play</code> &mdash; body: 16-bit mono PCM WAV at 44100 Hz. Optional header <code>X-Anim</code>: JSON array of steps, run in order; only <code>sleep</code> advances time:</p>
+<table>
+<tr><th>Step</th><th>Values</th></tr>
+<tr><td><code>["sleep", ms]</code></td><td>0&ndash;600000 ms of playback</td></tr>
+<tr><td><code>["preset", name]</code></td><td><code>none</code>, <code>typing</code>, <code>reading</code>, <code>thinking</code>, <code>wakeup</code></td></tr>
+<tr><td><code>["move", servo, to, ms?]</code></td><td><code>head</code>, <code>neck</code>, <code>hand_left</code>, <code>hand_right</code>, <code>body</code>; <code>to</code> &minus;1&ndash;1</td></tr>
+<tr><td><code>["eyes", mode]</code></td><td><code>idle</code> or a <code>/anim</code> name</td></tr>
+<tr><td><code>["look", x, y, ms?]</code></td><td><code>x</code> &minus;1 left to 1 right, <code>y</code> &minus;1 up to 1 down</td></tr>
+<tr><td><code>["open", amount, ms?]</code></td><td>0&ndash;1</td></tr>
+<tr><td><code>["blink"]</code></td><td></td></tr>
+<tr><td><code>["face", name]</code></td><td><code>idle</code>, <code>happy</code>, <code>laugh</code>, <code>wink</code>, <code>curious</code>, <code>thinking</code>, <code>surprise</code>, <code>smug</code>, <code>sleepy</code>, <code>sleep</code>, <code>sad</code>, <code>cry</code>, <code>angry</code>, <code>panic</code>, <code>shy</code>, <code>love</code></td></tr>
+</table>
 <p>POST <code>/test/servo</code> &mdash; query params:</p>
 <table>
 <tr><th>Param</th><th>Type</th><th>Range</th></tr>

From 4650b34df16f631c53e56964d1f385202b6456f9 Mon Sep 17 00:00:00 2001
From: shodan <mega@ioexception.at>
Date: Sun, 4 Oct 2026 10:34:02 +0200
Subject: [PATCH 06/21] feat(integrations): add a Claude Code skill for
 speaking and performing

The tiny-engineer-play skill teaches Claude to make a clip with the
machine's text-to-speech (or silence), convert it to the robot's WAV
format, time a timeline against the speech, and send it with the play
command. scripts/play resolves its real path so the skill also works
when symlinked into ~/.claude/skills.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VYDrnWNM6nbcQ1nx8aua93
---
 docs/integration.md                           |  8 ++
 .../tiny-engineer-claude-code/package.json    |  1 +
 .../skills/tiny-engineer-play/SKILL.md        | 83 +++++++++++++++++++
 .../skills/tiny-engineer-play/scripts/play    |  3 +
 4 files changed, 95 insertions(+)
 create mode 100644 packages/tiny-engineer-claude-code/skills/tiny-engineer-play/SKILL.md
 create mode 100755 packages/tiny-engineer-claude-code/skills/tiny-engineer-play/scripts/play

diff --git a/docs/integration.md b/docs/integration.md
index dcb7d760..36ea5812 100644
--- a/docs/integration.md
+++ b/docs/integration.md
@@ -249,6 +249,14 @@ node packages/tiny-engineer-claude-code/bin/tiny-engineer-claude-code.js play he
 
 `--anim-file dance.json` reads the timeline from a file. `--help` lists every step.
 
+To let Claude use it on its own in any project, install the bundled skill. It explains how to make a clip with text-to-speech, write the timeline, and fix errors:
+
+```bash
+ln -s "$PWD/packages/tiny-engineer-claude-code/skills/tiny-engineer-play" ~/.claude/skills/tiny-engineer-play
+```
+
+Then ask Claude something like "have the robot congratulate me on the green build".
+
 ### Smoke test
 
 ```bash
diff --git a/packages/tiny-engineer-claude-code/package.json b/packages/tiny-engineer-claude-code/package.json
index 03ee90c5..c1167280 100644
--- a/packages/tiny-engineer-claude-code/package.json
+++ b/packages/tiny-engineer-claude-code/package.json
@@ -12,6 +12,7 @@
   },
   "files": [
     "bin",
+    "skills",
     "src"
   ],
   "engines": {
diff --git a/packages/tiny-engineer-claude-code/skills/tiny-engineer-play/SKILL.md b/packages/tiny-engineer-claude-code/skills/tiny-engineer-play/SKILL.md
new file mode 100644
index 00000000..0934dce6
--- /dev/null
+++ b/packages/tiny-engineer-claude-code/skills/tiny-engineer-play/SKILL.md
@@ -0,0 +1,83 @@
+---
+name: tiny-engineer-play
+description: Make the Tiny Engineer desk robot speak and perform a custom animation (servo moves, gaze, blinks, animated faces) synced to a WAV clip, via its POST /play API. Use whenever the user asks the robot to say something, celebrate, react, wave, nod, dance, show a face or emotion, announce a result, or "tell me through the robot", and whenever they ask you to choreograph, script or test robot motion or eyes. Also use when debugging /play errors such as 415 "expected 16-bit mono PCM" or 400 "step N: ...".
+---
+
+# Tiny Engineer: speak and perform
+
+The robot plays a WAV clip while running a timeline of moves and eye changes. Send it with the script in this skill's base directory:
+
+```bash
+<base directory>/scripts/play clip.wav --anim '<timeline json>'
+```
+
+It reads `TINY_ENGINEER_URL` and `TINY_ENGINEER_TOKEN` from the environment (or `--url`). It prints the robot's JSON reply after the clip has finished playing and exits 1 with the reason when anything is wrong. The robot only answers one request at a time, so keep clips short (a few seconds to about 20 s); the hooks that animate the robot during normal work wait while a clip plays.
+
+## 1. Make the clip
+
+The robot accepts only 16-bit mono PCM WAV at its own sample rate. Generate speech with whatever text-to-speech the machine has, then convert:
+
+```bash
+espeak-ng -v en-us -s 165 -w /tmp/te-raw.wav "Build passed. Ship it!"     # Linux
+say --file-format=WAVE --data-format=LEI16@22050 -o /tmp/te-raw.wav "Build passed. Ship it!"  # macOS
+ffmpeg -y -loglevel error -i /tmp/te-raw.wav -ar 44100 -ac 1 -c:a pcm_s16le /tmp/te-clip.wav
+```
+
+For a silent performance, make silence of the right length:
+
+```bash
+ffmpeg -y -loglevel error -f lavfi -i anullsrc=r=44100:cl=mono -t 4 -c:a pcm_s16le /tmp/te-clip.wav
+```
+
+44100 Hz is the stock rate; some builds use 22050. If the reply is `expected 16-bit mono PCM at N Hz`, re-run the `ffmpeg` step with `-ar N`.
+
+Get the clip length to plan the timeline:
+
+```bash
+ffprobe -v error -show_entries format=duration -of csv=p=0 /tmp/te-clip.wav
+```
+
+## 2. Write the timeline
+
+A JSON array of steps. Steps run in order and only `sleep` advances time, so steps with no `sleep` between them start together. Time is measured in playback, so the motion stays in sync with the audio.
+
+| Step | Effect |
+| --- | --- |
+| `["sleep", ms]` | Wait `ms` of playback |
+| `["preset", name]` | Built-in motion loop with eyes: `none` (rest), `typing`, `reading`, `thinking`, `wakeup` |
+| `["move", servo, to, ms?]` | `head` (tilt), `neck` (pan), `hand_left`, `hand_right`, `body` (rotate) to `to` in -1..1, arriving after `ms`. Stops the running preset; other joints hold |
+| `["eyes", mode]` | Eye mode: `idle`, `typing`, `reading`, `thinking`, `ring`, `welcome`, `attention`, `error`, `abort`, `wakeup`, `dead` |
+| `["look", x, y, ms?]` | Gaze: `x` -1 screen left to 1 right, `y` -1 up to 1 down |
+| `["open", amount, ms?]` | Eyelids: 0 closed, 0.3 squint, 1 normal |
+| `["blink"]` | One blink |
+| `["face", name]` | Animated face: `idle`, `happy`, `laugh`, `wink`, `curious`, `thinking`, `surprise`, `smug`, `sleepy`, `sleep`, `sad`, `cry`, `angry`, `panic`, `shy`, `love` |
+
+Positions are relative to each robot's calibrated range (-1 = saved min, 1 = saved max), so they are safe on any build. The left and right hands use opposite scales: test a hand move before relying on which way is "up".
+
+A `face` stays until the next `look`, `open`, `eyes` or `preset`. When the clip ends the robot goes back to the `typing`, `reading` or `thinking` loop it was in before, otherwise to rest.
+
+Timing speech: `espeak-ng -s 165` speaks about 2.7 words per second. Put a gesture on the word it belongs to by summing the words before it, and start a move 100-200 ms before the stressed word so it lands on time. Moves of 200-500 ms read as deliberate; under 150 ms reads as a twitch.
+
+## 3. Send it
+
+```bash
+<base directory>/scripts/play /tmp/te-clip.wav --anim '[
+  ["preset","thinking"],
+  ["sleep",700], ["face","happy"], ["move","head",0.5,300], ["move","body",0.3,400],
+  ["sleep",900], ["look",-1,0,200], ["move","neck",-0.5,300],
+  ["sleep",800], ["blink"], ["preset","none"]
+]'
+```
+
+`--anim-file dance.json` reads the timeline from a file instead; pretty-printed JSON is fine either way.
+
+## Errors
+
+| Reply | Fix |
+| --- | --- |
+| `400 step N: ...` | Step `N` (0-based) is wrong: unknown servo, eye mode or face, a preset with its own sound (`ring`, `welcome`, ...), or bad numbers |
+| `415 expected 16-bit mono PCM at N Hz` | Convert with `ffmpeg ... -ar N -ac 1 -c:a pcm_s16le` |
+| `401 unauthorized` | Set `TINY_ENGINEER_TOKEN` to the robot's `access_token` |
+| `robot unreachable` | Check `TINY_ENGINEER_URL`; the robot must be on the same network |
+
+Full API reference: `docs/api.md` (`POST /play`) in the Tiny Engineer repository.
diff --git a/packages/tiny-engineer-claude-code/skills/tiny-engineer-play/scripts/play b/packages/tiny-engineer-claude-code/skills/tiny-engineer-play/scripts/play
new file mode 100755
index 00000000..a6076a61
--- /dev/null
+++ b/packages/tiny-engineer-claude-code/skills/tiny-engineer-play/scripts/play
@@ -0,0 +1,3 @@
+#!/bin/sh
+# Resolve the real path so the CLI is found when the skill directory is symlinked.
+exec node "$(dirname "$(readlink -f "$0")")/../../../bin/tiny-engineer-claude-code.js" play "$@"

From 8611360dee1a1f895b01b691c2bae86a0c187cc9 Mon Sep 17 00:00:00 2001
From: shodan <mega@ioexception.at>
Date: Sun, 4 Oct 2026 12:53:00 +0200
Subject: [PATCH 07/21] feat(scripts): speak in the robot's voice with word
 timings for /play

scripts/say.py is a uv script that runs Kokoro-82M text-to-speech
through a tin-can filter (band-pass with a short resonance, a 60 Hz ring
modulator and a bitcrushed flanger) and writes a 16-bit mono WAV at the
robot's sample rate. It prints each word's start in milliseconds so an
agent can place timeline steps on words. The tiny-engineer-play skill
makes clips with it and falls back to espeak-ng or macOS say without uv.

POST /play docs, the HTML index and the skill now state 22050 Hz, the
SAMPLE_RATE every build uses.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VYDrnWNM6nbcQ1nx8aua93
---
 docs/api.md                                   |   6 +-
 docs/integration.md                           |  14 +++
 .../skills/tiny-engineer-play/SKILL.md        |  45 +++++---
 .../skills/tiny-engineer-play/scripts/say     |   3 +
 scripts/say.py                                | 100 ++++++++++++++++++
 src/http/index_page.cpp                       |   2 +-
 6 files changed, 152 insertions(+), 18 deletions(-)
 create mode 100755 packages/tiny-engineer-claude-code/skills/tiny-engineer-play/scripts/say
 create mode 100755 scripts/say.py

diff --git a/docs/api.md b/docs/api.md
index 24173351..dbc43a4c 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -542,7 +542,7 @@ Streams a WAV to the speaker and optionally drives the robot from a timeline whi
 
 | Part | Value |
 | --- | --- |
-| Body | WAV, 16-bit mono PCM at 44100 Hz (the firmware `SAMPLE_RATE`). `Content-Length` is required. Chunks other than `fmt ` and `data` are skipped |
+| Body | WAV, 16-bit mono PCM at 22050 Hz (the firmware `SAMPLE_RATE`). `Content-Length` is required. Chunks other than `fmt ` and `data` are skipped |
 | `X-Anim` header | Optional JSON array of timeline steps, up to 8 KB and 256 steps |
 | `Authorization` | `Bearer <token>` when `access_token` is set |
 
@@ -574,7 +574,7 @@ curl -X POST http://tiny-engineer.local/play \
 { "ok": true, "played_ms": 3000 }
 ```
 
-The Claude Code CLI wraps this for agents: `tiny-engineer-claude-code play clip.wav --anim '[...]'` ([integration.md](integration.md#4-claude-code-dedicated-script)).
+The Claude Code CLI wraps this for agents: `tiny-engineer-claude-code play clip.wav --anim '[...]'` ([integration.md](integration.md#4-claude-code-dedicated-script)). [`scripts/say.py`](../scripts/say.py) makes a speech clip in this format and prints when each word starts ([integration.md](integration.md#speech-for-post-play)).
 
 Errors arrive before any audio plays:
 
@@ -582,7 +582,7 @@ Errors arrive before any audio plays:
 | --- | --- | --- |
 | `400` | `step N: ...` | Timeline step `N` (0-based) is invalid, names an unknown servo, eye mode or face, or a preset that plays its own sound |
 | `400` | `X-Anim is not a JSON array` | Header is not a JSON array |
-| `415` | `expected 16-bit mono PCM at 44100 Hz` | WAV format or sample rate differs |
+| `415` | `expected 16-bit mono PCM at 22050 Hz` | WAV format or sample rate differs |
 | `415` | `not a WAV file`, `no audio data` | Body is not a RIFF/WAVE file, or has no `data` chunk |
 
 ## Errors
diff --git a/docs/integration.md b/docs/integration.md
index 36ea5812..af2de79b 100644
--- a/docs/integration.md
+++ b/docs/integration.md
@@ -105,6 +105,20 @@ curl http://tiny-engineer.local/health
 
 More routes (tests, servo, web UI): [`api.md`](api.md).
 
+### Speech for `POST /play`
+
+[`scripts/say.py`](../scripts/say.py) speaks a line in the robot's voice: [Kokoro](https://huggingface.co/hexgrad/Kokoro-82M) text-to-speech through a tin-can filter, written as a WAV that [`POST /play`](api.md#post-play) accepts. It needs [uv](https://docs.astral.sh/uv/) and ffmpeg. The first run installs its Python dependencies and downloads the model (about 330 MB).
+
+```bash
+scripts/say.py "Build passed. Ship it!" -o /tmp/te-clip.wav
+```
+
+```json
+{"wav": "/tmp/te-clip.wav", "duration_ms": 2200, "words": [["Build", 375], ["passed", 650], ["Ship", 1188], ["it", 1475]]}
+```
+
+`words` holds the start of each word in milliseconds of the clip, so an agent can put a `move` or `face` step on the word it belongs to. `--voice` picks another [Kokoro voice](https://huggingface.co/hexgrad/Kokoro-82M/blob/main/VOICES.md) (default `am_michael`), `--plain` skips the filter, `--rate` matches a robot built with another sample rate.
+
 ---
 
 ## 2. Cursor dedicated script
diff --git a/packages/tiny-engineer-claude-code/skills/tiny-engineer-play/SKILL.md b/packages/tiny-engineer-claude-code/skills/tiny-engineer-play/SKILL.md
index 0934dce6..4dfb5ffa 100644
--- a/packages/tiny-engineer-claude-code/skills/tiny-engineer-play/SKILL.md
+++ b/packages/tiny-engineer-claude-code/skills/tiny-engineer-play/SKILL.md
@@ -15,28 +15,39 @@ It reads `TINY_ENGINEER_URL` and `TINY_ENGINEER_TOKEN` from the environment (or
 
 ## 1. Make the clip
 
-The robot accepts only 16-bit mono PCM WAV at its own sample rate. Generate speech with whatever text-to-speech the machine has, then convert:
+The robot accepts only 16-bit mono PCM WAV at its own sample rate. Make speech in the robot's voice with the `say` script in this skill's base directory. It needs `uv` and `ffmpeg`; the first run installs its dependencies and downloads the voice model, so allow a few minutes, and later runs take about 15 s.
 
 ```bash
-espeak-ng -v en-us -s 165 -w /tmp/te-raw.wav "Build passed. Ship it!"     # Linux
-say --file-format=WAVE --data-format=LEI16@22050 -o /tmp/te-raw.wav "Build passed. Ship it!"  # macOS
-ffmpeg -y -loglevel error -i /tmp/te-raw.wav -ar 44100 -ac 1 -c:a pcm_s16le /tmp/te-clip.wav
+<base directory>/scripts/say "Build passed. Ship it!" -o /tmp/te-clip.wav
 ```
 
-For a silent performance, make silence of the right length:
+It prints the clip length and the start of every word in milliseconds:
 
-```bash
-ffmpeg -y -loglevel error -f lavfi -i anullsrc=r=44100:cl=mono -t 4 -c:a pcm_s16le /tmp/te-clip.wav
+```json
+{"wav": "/tmp/te-clip.wav", "duration_ms": 2200, "words": [["Build", 375], ["passed", 650], ["Ship", 1188], ["it", 1475]]}
 ```
 
-44100 Hz is the stock rate; some builds use 22050. If the reply is `expected 16-bit mono PCM at N Hz`, re-run the `ffmpeg` step with `-ar N`.
+Build the timeline from these timings.
+
+Options: `--voice bm_george` for a British voice (any Kokoro voice; the default is `am_michael`), `--speed 0.9` to slow down, `--plain` for the voice without the robot filter, `--rate N` for a robot with another sample rate.
 
-Get the clip length to plan the timeline:
+If `say` is unavailable (no `uv`), fall back to the machine's own text-to-speech and convert it. There are no word timings then, so estimate from `ffprobe` duration divided by the word count:
 
 ```bash
+espeak-ng -v en-us -s 165 -w /tmp/te-raw.wav "Build passed. Ship it!"     # Linux
+say --file-format=WAVE --data-format=LEI16@22050 -o /tmp/te-raw.wav "Build passed. Ship it!"  # macOS built-in say
+ffmpeg -y -loglevel error -i /tmp/te-raw.wav -ar 22050 -ac 1 -c:a pcm_s16le /tmp/te-clip.wav
 ffprobe -v error -show_entries format=duration -of csv=p=0 /tmp/te-clip.wav
 ```
 
+For a silent performance, make silence of the right length:
+
+```bash
+ffmpeg -y -loglevel error -f lavfi -i anullsrc=r=22050:cl=mono -t 4 -c:a pcm_s16le /tmp/te-clip.wav
+```
+
+22050 Hz is the stock rate. If the reply is `expected 16-bit mono PCM at N Hz`, re-run `say` with `--rate N` (or the `ffmpeg` step with `-ar N`).
+
 ## 2. Write the timeline
 
 A JSON array of steps. Steps run in order and only `sleep` advances time, so steps with no `sleep` between them start together. Time is measured in playback, so the motion stays in sync with the audio.
@@ -56,19 +67,25 @@ Positions are relative to each robot's calibrated range (-1 = saved min, 1 = sav
 
 A `face` stays until the next `look`, `open`, `eyes` or `preset`. When the clip ends the robot goes back to the `typing`, `reading` or `thinking` loop it was in before, otherwise to rest.
 
-Timing speech: `espeak-ng -s 165` speaks about 2.7 words per second. Put a gesture on the word it belongs to by summing the words before it, and start a move 100-200 ms before the stressed word so it lands on time. Moves of 200-500 ms read as deliberate; under 150 ms reads as a twitch.
+Timing speech: `sleep` takes the gap between steps, not an absolute time, so turn the word starts into differences. To land a gesture on a word, start the move 100-200 ms before that word's start so it arrives on the stressed syllable. Moves of 200-500 ms read as deliberate; under 150 ms reads as a twitch. Fill pauses between sentences (a gap of 300 ms or more between words) with a blink, a glance or a new face.
 
 ## 3. Send it
 
+For the clip above, a nod that lands on "Build" (375 ms) and a happy face with a wave on "Ship" (1188 ms):
+
 ```bash
 <base directory>/scripts/play /tmp/te-clip.wav --anim '[
   ["preset","thinking"],
-  ["sleep",700], ["face","happy"], ["move","head",0.5,300], ["move","body",0.3,400],
-  ["sleep",900], ["look",-1,0,200], ["move","neck",-0.5,300],
-  ["sleep",800], ["blink"], ["preset","none"]
+  ["sleep",175], ["move","head",0.5,200],
+  ["sleep",475], ["move","head",0,300],
+  ["sleep",350], ["face","happy"], ["move","hand_right",0.8,200],
+  ["sleep",400], ["move","hand_right",0.2,250],
+  ["sleep",450], ["blink"], ["preset","none"]
 ]'
 ```
 
+The sleeps add up to the target times: 175 is 200 ms before "Build", 175 + 475 = 650 is "passed", 650 + 350 = 1000 is about 190 ms before "Ship".
+
 `--anim-file dance.json` reads the timeline from a file instead; pretty-printed JSON is fine either way.
 
 ## Errors
@@ -76,7 +93,7 @@ Timing speech: `espeak-ng -s 165` speaks about 2.7 words per second. Put a gestu
 | Reply | Fix |
 | --- | --- |
 | `400 step N: ...` | Step `N` (0-based) is wrong: unknown servo, eye mode or face, a preset with its own sound (`ring`, `welcome`, ...), or bad numbers |
-| `415 expected 16-bit mono PCM at N Hz` | Convert with `ffmpeg ... -ar N -ac 1 -c:a pcm_s16le` |
+| `415 expected 16-bit mono PCM at N Hz` | Re-run `say` with `--rate N`, or convert with `ffmpeg ... -ar N -ac 1 -c:a pcm_s16le` |
 | `401 unauthorized` | Set `TINY_ENGINEER_TOKEN` to the robot's `access_token` |
 | `robot unreachable` | Check `TINY_ENGINEER_URL`; the robot must be on the same network |
 
diff --git a/packages/tiny-engineer-claude-code/skills/tiny-engineer-play/scripts/say b/packages/tiny-engineer-claude-code/skills/tiny-engineer-play/scripts/say
new file mode 100755
index 00000000..ba0a186d
--- /dev/null
+++ b/packages/tiny-engineer-claude-code/skills/tiny-engineer-play/scripts/say
@@ -0,0 +1,3 @@
+#!/bin/sh
+# Resolve the real path so the repo script is found when the skill directory is symlinked.
+exec "$(dirname "$(readlink -f "$0")")/../../../../../scripts/say.py" "$@"
diff --git a/scripts/say.py b/scripts/say.py
new file mode 100755
index 00000000..1c1a697e
--- /dev/null
+++ b/scripts/say.py
@@ -0,0 +1,100 @@
+#!/usr/bin/env -S uv run --script
+# /// script
+# requires-python = ">=3.10,<3.13"
+# dependencies = [
+#     "kokoro>=0.9.4",
+#     "transformers>=4.45",
+#     "en_core_web_sm @ https://github.com/explosion/spacy-models/releases/download/en_core_web_sm-3.8.0/en_core_web_sm-3.8.0-py3-none-any.whl",
+# ]
+# ///
+"""Speak text with Kokoro in the robot's voice and print word timings for a /play timeline."""
+
+import argparse
+import json
+import os
+import subprocess
+import sys
+import warnings
+
+import espeakng_loader
+
+warnings.simplefilter("ignore")
+os.environ.setdefault("HF_HUB_VERBOSITY", "error")
+
+# The bundled espeak-ng library looks for its data at the path it was built in.
+os.environ.setdefault("ESPEAK_DATA_PATH", espeakng_loader.get_data_path())
+
+import numpy  # noqa: E402
+from kokoro import KPipeline  # noqa: E402
+
+KOKORO_RATE = 24000
+
+# Band-limited "can" resonance, blended with a 60 Hz ring modulator and a bitcrushed flanger.
+ROBOT_FILTER = (
+    "[0:a]highpass=f=320,lowpass=f=3400,asplit=3[a][b][c];"
+    "[a]aecho=0.8:0.7:6|11:0.45|0.3,acompressor=threshold=0.1:ratio=6[can];"
+    f"sine=f=60:r={KOKORO_RATE}[carrier];[b][carrier]amultiply,volume=2[ring];"
+    "[c]acrusher=bits=6:mode=log:aa=1:samples=2,flanger=delay=2:depth=1:speed=0.3[crush];"
+    "[can][ring][crush]amix=inputs=3:weights=1 0.6 0.7:duration=first,"
+    "loudnorm=I=-15:TP=-1:LRA=7[out]"
+)
+PLAIN_FILTER = "[0:a]loudnorm=I=-15:TP=-1:LRA=7[out]"
+
+
+def parse_args():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("text")
+    parser.add_argument("-o", "--output", default="/tmp/te-clip.wav")
+    parser.add_argument("--voice", default="am_michael", help="Kokoro voice; the first letter picks the accent (a = US, b = UK)")
+    parser.add_argument("--speed", type=float, default=1.0)
+    parser.add_argument("--rate", type=int, default=22050, help="the robot's sample rate")
+    parser.add_argument("--plain", action="store_true", help="skip the robot filter")
+    return parser.parse_args()
+
+
+def synthesize(text, voice, speed):
+    """Return the audio and [word, start_ms] pairs, offset across Kokoro's chunks."""
+    pipeline = KPipeline(lang_code=voice[0], repo_id="hexgrad/Kokoro-82M")
+    chunks = []
+    words = []
+    offset_ms = 0
+
+    for result in pipeline(text, voice=voice, speed=speed):
+        audio = result.audio.numpy()
+        words += [
+            [token.text, offset_ms + round(token.start_ts * 1000)]
+            for token in result.tokens or []
+            if token.start_ts is not None and any(char.isalnum() for char in token.text)
+        ]
+        chunks.append(audio)
+        offset_ms += round(len(audio) * 1000 / KOKORO_RATE)
+
+    return numpy.concatenate(chunks), words
+
+
+def write_wav(audio, path, rate, plain):
+    subprocess.run(
+        [
+            "ffmpeg", "-y", "-v", "error",
+            "-f", "f32le", "-ar", str(KOKORO_RATE), "-ac", "1", "-i", "-",
+            "-filter_complex", PLAIN_FILTER if plain else ROBOT_FILTER,
+            "-map", "[out]", "-ar", str(rate), "-ac", "1", "-c:a", "pcm_s16le", path,
+        ],
+        input=audio.astype(numpy.float32).tobytes(),
+        check=True,
+    )
+
+
+def main():
+    args = parse_args()
+    audio, words = synthesize(args.text, args.voice, args.speed)
+    if not words:
+        sys.exit("Kokoro produced no speech for that text")
+
+    write_wav(audio, args.output, args.rate, args.plain)
+    duration_ms = round(len(audio) * 1000 / KOKORO_RATE)
+    print(json.dumps({"wav": args.output, "duration_ms": duration_ms, "words": words}))
+
+
+if __name__ == "__main__":
+    main()
diff --git a/src/http/index_page.cpp b/src/http/index_page.cpp
index bae44a78..15230a79 100644
--- a/src/http/index_page.cpp
+++ b/src/http/index_page.cpp
@@ -285,7 +285,7 @@ body:not(.setup-mode) #setup-wizard{display:none!important}
 <tr><td><code>wakeup</code></td><td>One-shot sleep-inertia wake</td></tr>
 <tr><td><code>sleep</code></td><td>Close eyes and sleep</td></tr>
 </table>
-<p>POST <code>/play</code> &mdash; body: 16-bit mono PCM WAV at 44100 Hz. Optional header <code>X-Anim</code>: JSON array of steps, run in order; only <code>sleep</code> advances time:</p>
+<p>POST <code>/play</code> &mdash; body: 16-bit mono PCM WAV at 22050 Hz. Optional header <code>X-Anim</code>: JSON array of steps, run in order; only <code>sleep</code> advances time:</p>
 <table>
 <tr><th>Step</th><th>Values</th></tr>
 <tr><td><code>["sleep", ms]</code></td><td>0&ndash;600000 ms of playback</td></tr>

From 3410452949d21c09a4ac9cb639358dd06d1d0a2d Mon Sep 17 00:00:00 2001
From: shodan <mega@ioexception.at>
Date: Sun, 4 Oct 2026 13:03:16 +0200
Subject: [PATCH 08/21] refactor(anim): reuse shared helpers in the /play
 timeline and scripted eyes

- Scripted look and open use anim::EasedMove and eyes::renderEye instead of
  a private tween and lid maths; clearScript() resets them.
- A scripted face only flushes the OLED when its frame changes, saving
  about two I2C flushes per 100 ms during playback.
- The play session reads the parser's sample count instead of keeping its
  own, and parses X-Anim inline.
- Timeline matches preset/eyes/face from one table and reserves its steps.
- TinyEngineerExpressions gains fromName(), the reverse of name().

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VYDrnWNM6nbcQ1nx8aua93
---
 .../src/TinyEngineerExpressions.cpp           | 10 +++
 .../src/TinyEngineerExpressions.h             |  3 +
 src/animation/timeline.cpp                    | 34 +++++----
 src/animation/timeline_player.cpp             | 14 ++--
 src/audio/wav_parser.cpp                      |  6 +-
 src/audio/wav_parser.h                        |  2 +-
 src/display/eyes/script.cpp                   | 70 ++++++++-----------
 src/http/http_server.cpp                      |  2 +-
 src/http/play_handlers.cpp                    | 31 ++++----
 test/test_expressions/test_expressions.cpp    | 15 ++++
 10 files changed, 100 insertions(+), 87 deletions(-)

diff --git a/lib/TinyEngineerExpressions/src/TinyEngineerExpressions.cpp b/lib/TinyEngineerExpressions/src/TinyEngineerExpressions.cpp
index fce7e7bd..90c00fef 100644
--- a/lib/TinyEngineerExpressions/src/TinyEngineerExpressions.cpp
+++ b/lib/TinyEngineerExpressions/src/TinyEngineerExpressions.cpp
@@ -35,6 +35,16 @@ const char* name(Expression expression) {
   return index < kExpressionCount ? kNames[index] : nullptr;
 }
 
+bool fromName(const char* text, Expression& expression) {
+  for (std::size_t i = 0; text != nullptr && i < kExpressionCount; i++) {
+    if (std::strcmp(kNames[i], text) == 0) {
+      expression = static_cast<Expression>(i);
+      return true;
+    }
+  }
+  return false;
+}
+
 bool render(Expression expression, uint32_t elapsedMs,
             uint8_t* output, std::size_t outputSize) {
   const auto index = static_cast<uint8_t>(expression);
diff --git a/lib/TinyEngineerExpressions/src/TinyEngineerExpressions.h b/lib/TinyEngineerExpressions/src/TinyEngineerExpressions.h
index aaa96967..e5a7dcfa 100644
--- a/lib/TinyEngineerExpressions/src/TinyEngineerExpressions.h
+++ b/lib/TinyEngineerExpressions/src/TinyEngineerExpressions.h
@@ -53,6 +53,9 @@ constexpr uint32_t kLoopDurationMs = 3000;
 // enum values return nullptr.
 const char* name(Expression expression);
 
+// Reverse of name(); false leaves `expression` unchanged for unknown names.
+bool fromName(const char* text, Expression& expression);
+
 // Render the frame at elapsedMs since the caller selected this expression.
 // The caller owns timing, selection, and display output. Animation loops every
 // kLoopDurationMs; this function never reads a clock or accesses a display.
diff --git a/src/animation/timeline.cpp b/src/animation/timeline.cpp
index 99073fc1..45f5a8f5 100644
--- a/src/animation/timeline.cpp
+++ b/src/animation/timeline.cpp
@@ -2,6 +2,7 @@
 
 #include <ArduinoJson.h>
 
+#include <algorithm>
 #include <cstdio>
 #include <cstring>
 #include <strings.h>
@@ -21,10 +22,6 @@ bool findServo(const char* name, uint8_t& index) {
   return false;
 }
 
-float clampTo(float value, float lo, float hi) {
-  return value < lo ? lo : (value > hi ? hi : value);
-}
-
 bool isMs(JsonVariantConst value) {
   return value.is<uint32_t>() && value.as<uint32_t>() <= Timeline::kMaxSleepMs;
 }
@@ -56,19 +53,31 @@ const char* parseStep(JsonArrayConst item, const Timeline::Names& names, uint32_
     return nullptr;
   }
 
-  if (strcmp(command, "preset") == 0 || strcmp(command, "eyes") == 0 || strcmp(command, "face") == 0) {
-    const Kind kind = command[0] == 'p' ? Kind::Preset : (command[0] == 'e' ? Kind::Eyes : Kind::Face);
-    const Timeline::NameResolver resolve = kind == Kind::Preset ? names.preset : (kind == Kind::Eyes ? names.eyes : names.face);
+  const struct {
+    const char* command;
+    Kind kind;
+    Timeline::NameResolver resolve;
+  } named[] = {
+    {"preset", Kind::Preset, names.preset},
+    {"eyes", Kind::Eyes, names.eyes},
+    {"face", Kind::Face, names.face},
+  };
+
+  for (const auto& entry : named) {
+    if (strcmp(command, entry.command) != 0) {
+      continue;
+    }
+
     const char* name = item[1].as<const char*>();
     uint8_t id = 0;
 
     if (name == nullptr) {
       return "needs a name";
     }
-    if (const char* reason = resolve(name, id)) {
+    if (const char* reason = entry.resolve(name, id)) {
       return reason;
     }
-    step = Timeline::Step{atMs, kind, id, 0.0f, 0.0f, 0};
+    step = Timeline::Step{atMs, entry.kind, id, 0.0f, 0.0f, 0};
     return nullptr;
   }
 
@@ -94,8 +103,8 @@ const char* parseStep(JsonArrayConst item, const Timeline::Names& names, uint32_
       atMs,
       Kind::Look,
       0,
-      clampTo(item[1].as<float>(), -1.0f, 1.0f),
-      clampTo(item[2].as<float>(), -1.0f, 1.0f),
+      servoSaturateNorm(item[1].as<float>()),
+      servoSaturateNorm(item[2].as<float>()),
       item[3].as<uint32_t>()
     };
     return nullptr;
@@ -105,7 +114,7 @@ const char* parseStep(JsonArrayConst item, const Timeline::Names& names, uint32_
     if (!item[1].is<float>() || !isOptionalMs(item[2])) {
       return "open needs an amount 0..1 and optional duration ms";
     }
-    step = Timeline::Step{atMs, Kind::Open, 0, clampTo(item[1].as<float>(), 0.0f, 1.0f), 0.0f, item[2].as<uint32_t>()};
+    step = Timeline::Step{atMs, Kind::Open, 0, std::clamp(item[1].as<float>(), 0.0f, 1.0f), 0.0f, item[2].as<uint32_t>()};
     return nullptr;
   }
 
@@ -136,6 +145,7 @@ std::optional<Timeline> Timeline::parse(
   }
 
   Timeline timeline;
+  timeline.steps_.reserve(items.size());
   uint32_t atMs = 0;
   unsigned index = 0;
 
diff --git a/src/animation/timeline_player.cpp b/src/animation/timeline_player.cpp
index 70dfa54c..ba67c59b 100644
--- a/src/animation/timeline_player.cpp
+++ b/src/animation/timeline_player.cpp
@@ -48,18 +48,14 @@ const char* resolveEyes(const char* name, uint8_t& id) {
 }
 
 const char* resolveFace(const char* name, uint8_t& id) {
-  namespace expressions = tiny_engineer::expressions;
+  tiny_engineer::expressions::Expression face;
 
-  for (uint8_t i = 0; i < expressions::kExpressionCount; i++) {
-    const char* candidate = expressions::name(static_cast<expressions::Expression>(i));
-
-    if (candidate != nullptr && strcmp(candidate, name) == 0) {
-      id = i;
-      return nullptr;
-    }
+  if (!tiny_engineer::expressions::fromName(name, face)) {
+    return "unknown face";
   }
 
-  return "unknown face";
+  id = static_cast<uint8_t>(face);
+  return nullptr;
 }
 
 const Timeline::Names kNames = {resolvePreset, resolveEyes, resolveFace};
diff --git a/src/audio/wav_parser.cpp b/src/audio/wav_parser.cpp
index 7fd06876..a7cfb164 100644
--- a/src/audio/wav_parser.cpp
+++ b/src/audio/wav_parser.cpp
@@ -102,10 +102,6 @@ const char* WavStreamParser::error() const {
   return failed() ? message_ : nullptr;
 }
 
-bool WavStreamParser::reachedPcm() const {
-  return reachedPcm_;
-}
-
 uint32_t WavStreamParser::samplesDelivered() const {
   return samplesDelivered_;
 }
@@ -226,8 +222,8 @@ void WavStreamParser::flush() {
     return;
   }
 
-  sink_.onPcm(batch_, batchFill_);
   samplesDelivered_ += batchFill_;
+  sink_.onPcm(batch_, batchFill_);
   batchFill_ = 0;
 }
 
diff --git a/src/audio/wav_parser.h b/src/audio/wav_parser.h
index 35e58e8c..f0c8bca4 100644
--- a/src/audio/wav_parser.h
+++ b/src/audio/wav_parser.h
@@ -24,7 +24,7 @@ class WavStreamParser {
   bool failed() const;
   // Human-readable reason when failed(), else nullptr.
   const char* error() const;
-  bool reachedPcm() const;
+  // Includes the batch currently being handed to Sink::onPcm.
   uint32_t samplesDelivered() const;
 
 private:
diff --git a/src/display/eyes/script.cpp b/src/display/eyes/script.cpp
index 03681e5e..0de15208 100644
--- a/src/display/eyes/script.cpp
+++ b/src/display/eyes/script.cpp
@@ -15,53 +15,29 @@ namespace expressions = tiny_engineer::expressions;
 constexpr float kLookRangeX = 16.0f;
 constexpr float kLookRangeY = 8.0f;
 
-struct Tween {
-  float from;
-  float to;
-  uint32_t startMs;
-  uint32_t durationMs;
-
-  float at(uint32_t now) const {
-    const float t = anim::easeInOutCubic(eyes::moveProgress(now, startMs, durationMs));
-    return from + (to - from) * t;
-  }
-
-  void retarget(float target, uint32_t durationMs_, uint32_t now) {
-    from = at(now);
-    to = target;
-    startMs = now;
-    durationMs = durationMs_;
-  }
-};
+anim::EasedMove g_lookX = {};
+anim::EasedMove g_lookY = {};
+anim::EasedMove g_open = {1.0f, 1.0f, 0, 0, false};
 
 bool g_posing = false;
-Tween g_lookX = {0.0f, 0.0f, 0, 0};
-Tween g_lookY = {0.0f, 0.0f, 0, 0};
-Tween g_open = {1.0f, 1.0f, 0, 0};
-
 bool g_faceShowing = false;
 expressions::Expression g_face = expressions::Expression::Idle;
 uint32_t g_faceStartedMs = 0;
+uint32_t g_faceFrameDrawn = UINT32_MAX;
+
+void retarget(anim::EasedMove& move, float target, uint32_t durationMs, uint32_t now) {
+  anim::beginEasedMove(move, anim::easedMoveValue(move, now), target, now, durationMs);
+}
 
 Eye scriptedEye(const Eye& base, uint32_t now) {
-  const int16_t height = static_cast<int16_t>(base.height * g_open.at(now));
-
-  return {
-    static_cast<int16_t>(base.x + g_lookX.at(now) * kLookRangeX),
-    static_cast<int16_t>(base.y + g_lookY.at(now) * kLookRangeY + (base.height - height) / 2),
-    base.width,
-    height
-  };
+  Eye eye = eyes::renderEye(base, anim::easedMoveValue(g_open, now));
+  eye.x += static_cast<int16_t>(anim::easedMoveValue(g_lookX, now) * kLookRangeX);
+  eye.y += static_cast<int16_t>(anim::easedMoveValue(g_lookY, now) * kLookRangeY);
+  return eye;
 }
 
 void beginPosing() {
-  if (!g_posing) {
-    g_lookX = {0.0f, 0.0f, 0, 0};
-    g_lookY = {0.0f, 0.0f, 0, 0};
-    g_open = {1.0f, 1.0f, 0, 0};
-    g_posing = true;
-  }
-
+  g_posing = true;
   g_faceShowing = false;
   eyes::requestForceRedraw();
 }
@@ -70,13 +46,13 @@ void beginPosing() {
 
 void eyesLookAt(float x, float y, uint32_t durationMs, uint32_t now) {
   beginPosing();
-  g_lookX.retarget(x, durationMs, now);
-  g_lookY.retarget(y, durationMs, now);
+  retarget(g_lookX, x, durationMs, now);
+  retarget(g_lookY, y, durationMs, now);
 }
 
 void eyesSetOpen(float amount, uint32_t durationMs, uint32_t now) {
   beginPosing();
-  g_open.retarget(amount, durationMs, now);
+  retarget(g_open, amount, durationMs, now);
 }
 
 void eyesBlink(uint32_t now) {
@@ -86,6 +62,7 @@ void eyesBlink(uint32_t now) {
 void eyesShowFace(uint8_t expression, uint32_t now) {
   g_face = static_cast<expressions::Expression>(expression);
   g_faceStartedMs = now;
+  g_faceFrameDrawn = UINT32_MAX;
   g_faceShowing = true;
   eyes::requestForceRedraw();
 }
@@ -107,11 +84,22 @@ bool drawScriptFace(uint32_t now) {
     return false;
   }
 
-  drawKaomojiFrame(g_face, now - g_faceStartedMs);
+  // Faces change frame every kFrameDurationMs; skip the I2C flush in between.
+  const uint32_t elapsed = now - g_faceStartedMs;
+  const uint32_t frame = elapsed / expressions::kFrameDurationMs;
+
+  if (frame != g_faceFrameDrawn || forceRedraw()) {
+    drawKaomojiFrame(g_face, elapsed);
+    g_faceFrameDrawn = frame;
+  }
+
   return true;
 }
 
 void clearScript() {
+  g_lookX = {0.0f, 0.0f, 0, 0, false};
+  g_lookY = {0.0f, 0.0f, 0, 0, false};
+  g_open = {1.0f, 1.0f, 0, 0, false};
   g_posing = false;
   g_faceShowing = false;
 }
diff --git a/src/http/http_server.cpp b/src/http/http_server.cpp
index adcb1e86..1fad3a59 100644
--- a/src/http/http_server.cpp
+++ b/src/http/http_server.cpp
@@ -18,7 +18,7 @@ void startHttpServer() {
   refreshMdnsHostname();
 
   static const char* kCollectHeaders[] = {"Authorization", "X-Anim"};
-  server.collectHeaders(kCollectHeaders, 2);
+  server.collectHeaders(kCollectHeaders, sizeof(kCollectHeaders) / sizeof(kCollectHeaders[0]));
 
   registerHttpRoutes();
   server.begin();
diff --git a/src/http/play_handlers.cpp b/src/http/play_handlers.cpp
index 4ef19eed..42e30ca2 100644
--- a/src/http/play_handlers.cpp
+++ b/src/http/play_handlers.cpp
@@ -26,7 +26,6 @@ class PlaySession : public WavStreamParser::Sink {
     parser_.reset();
     player_.reset();
     rejectCode_ = 0;
-    samplesWritten_ = 0;
 
     if (!settingsWifiConfigured()) {
       reject(503, "wifi not configured");
@@ -44,13 +43,23 @@ class PlaySession : public WavStreamParser::Sink {
 
     const String& header = server.header("X-Anim");
 
-    if (header.length() > 0 && acceptTimeline(header.c_str(), header.length()) != nullptr) {
+    if (header.length() == 0) {
+      return;
+    }
+
+    std::optional<Timeline> timeline = Timeline::parse(header.c_str(), header.length(), TimelinePlayer::names(), error_, sizeof(error_));
+
+    if (!timeline) {
       reject(400, error_);
+      return;
     }
+
+    player_.emplace(std::move(*timeline));
+    player_->advance(0);
   }
 
   void feed(const uint8_t* bytes, size_t length) {
-    if (rejectCode_ == 0 && parser_ && !parser_->failed()) {
+    if (rejectCode_ == 0 && parser_) {
       parser_->feed(bytes, length);
     }
   }
@@ -86,7 +95,6 @@ class PlaySession : public WavStreamParser::Sink {
 
   void onPcm(const int16_t* samples, size_t count) override {
     writeMonoToSpeaker(samples, count);
-    samplesWritten_ += count;
 
     if (player_) {
       player_->advance(playedMs());
@@ -102,22 +110,9 @@ class PlaySession : public WavStreamParser::Sink {
   std::optional<WavStreamParser> parser_;
   std::optional<TimelinePlayer> player_;
   int rejectCode_ = 0;
-  uint32_t samplesWritten_ = 0;
   char error_[96] = {};
   char body_[128] = {};
 
-  const char* acceptTimeline(const char* json, size_t length) {
-    std::optional<Timeline> timeline = Timeline::parse(json, length, TimelinePlayer::names(), error_, sizeof(error_));
-
-    if (!timeline) {
-      return error_;
-    }
-
-    player_.emplace(std::move(*timeline));
-    player_->advance(0);
-    return nullptr;
-  }
-
   void reject(int code, const char* message) {
     rejectCode_ = code;
     formatError(message);
@@ -128,7 +123,7 @@ class PlaySession : public WavStreamParser::Sink {
   }
 
   uint32_t playedMs() const {
-    return static_cast<uint32_t>(samplesWritten_ * 1000ULL / SAMPLE_RATE);
+    return static_cast<uint32_t>(parser_->samplesDelivered() * 1000ULL / SAMPLE_RATE);
   }
 };
 
diff --git a/test/test_expressions/test_expressions.cpp b/test/test_expressions/test_expressions.cpp
index 4aa4096e..37910bb5 100644
--- a/test/test_expressions/test_expressions.cpp
+++ b/test/test_expressions/test_expressions.cpp
@@ -90,9 +90,24 @@ void test_callers_can_render_independently() {
   TEST_ASSERT_EQUAL_UINT8_ARRAY(first, again, sizeof first);
 }
 
+void test_from_name_round_trips_every_name() {
+  for (std::size_t i = 0; i < expr::kExpressionCount; i++) {
+    const auto expected = static_cast<expr::Expression>(i);
+    auto parsed = expr::Expression::Idle;
+    TEST_ASSERT_TRUE(expr::fromName(expr::name(expected), parsed));
+    TEST_ASSERT_EQUAL_UINT8(i, static_cast<uint8_t>(parsed));
+  }
+
+  auto untouched = expr::Expression::Love;
+  TEST_ASSERT_FALSE(expr::fromName("grumpy", untouched));
+  TEST_ASSERT_FALSE(expr::fromName(nullptr, untouched));
+  TEST_ASSERT_TRUE(untouched == expr::Expression::Love);
+}
+
 int main() {
   UNITY_BEGIN();
   RUN_TEST(test_names_and_invalid_ids);
+  RUN_TEST(test_from_name_round_trips_every_name);
   RUN_TEST(test_all_frames_match_original_designs);
   RUN_TEST(test_invalid_inputs_leave_buffer_untouched);
   RUN_TEST(test_frame_timing_and_loop_boundaries);

From 8cdee58eeb53c59e0c7bf0a6417287b2b68d93ae Mon Sep 17 00:00:00 2001
From: shodan <mega@ioexception.at>
Date: Sun, 4 Oct 2026 13:03:16 +0200
Subject: [PATCH 09/21] refactor(integrations): share robot fetch plumbing
 between anim and play

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VYDrnWNM6nbcQ1nx8aua93
---
 .../tiny-engineer-claude-code/src/play.js     | 19 ++++++------
 .../tiny-engineer-claude-code/src/post.js     | 30 ++++++++++++-------
 2 files changed, 28 insertions(+), 21 deletions(-)

diff --git a/packages/tiny-engineer-claude-code/src/play.js b/packages/tiny-engineer-claude-code/src/play.js
index 269a3b02..77a11f8b 100644
--- a/packages/tiny-engineer-claude-code/src/play.js
+++ b/packages/tiny-engineer-claude-code/src/play.js
@@ -1,5 +1,7 @@
 import { readFileSync } from "node:fs";
 
+import { robotFetch } from "./post.js";
+
 // The robot answers once the clip has finished playing.
 const PLAY_TIMEOUT_MS = 10 * 60 * 1000;
 
@@ -10,7 +12,6 @@ const PLAY_TIMEOUT_MS = 10 * 60 * 1000;
 export function parsePlayArgs(argv) {
   /** @type {{ wavPath?: string, anim?: string, url?: string }} */
   const opts = {};
-  let animSource;
 
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
@@ -23,8 +24,7 @@ export function parsePlayArgs(argv) {
         opts.url = value;
         continue;
       }
-      if (animSource) return { error: "use --anim or --anim-file, not both" };
-      animSource = arg;
+      if (opts.anim !== undefined) return { error: "use --anim or --anim-file, not both" };
       try {
         opts.anim = arg === "--anim" ? value : readFileSync(value, "utf8");
       } catch (err) {
@@ -59,14 +59,13 @@ export async function postPlay({ baseUrl, wav, anim, token }) {
   /** @type {Record<string, string>} */
   const headers = { "Content-Type": "audio/wav" };
   if (anim) headers["X-Anim"] = anim;
-  if (token) headers.Authorization = `Bearer ${token}`;
 
-  const response = await fetch(`${baseUrl.replace(/\/+$/, "")}/play`, {
-    method: "POST",
-    headers,
-    body: wav,
-    signal: AbortSignal.timeout(PLAY_TIMEOUT_MS),
-  });
+  const response = await robotFetch(
+    baseUrl,
+    "/play",
+    { method: "POST", headers, body: wav, signal: AbortSignal.timeout(PLAY_TIMEOUT_MS) },
+    token,
+  );
 
   return { ok: response.ok, status: response.status, body: await response.text() };
 }
diff --git a/packages/tiny-engineer-claude-code/src/post.js b/packages/tiny-engineer-claude-code/src/post.js
index ec6d38aa..0be32a1b 100644
--- a/packages/tiny-engineer-claude-code/src/post.js
+++ b/packages/tiny-engineer-claude-code/src/post.js
@@ -1,3 +1,16 @@
+/**
+ * fetch() against the robot: joins base URL and path and adds the Bearer token when set.
+ * @param {string} baseUrl
+ * @param {string} path
+ * @param {RequestInit} init
+ * @param {string | null} [token]
+ */
+export function robotFetch(baseUrl, path, init, token = null) {
+  const headers = { ...init.headers };
+  if (token) headers.Authorization = `Bearer ${token}`;
+  return fetch(`${baseUrl.replace(/\/+$/, "")}${path}`, { ...init, headers });
+}
+
 /**
  * POST /anim?name=… with a 2s timeout. Errors are swallowed.
  * @param {string} baseUrl
@@ -5,18 +18,13 @@
  * @param {string | null} [token]
  */
 export async function postAnim(baseUrl, animName, token = null) {
-  const base = baseUrl.replace(/\/+$/, "");
-  const url = `${base}/anim?name=${encodeURIComponent(animName)}`;
-  /** @type {RequestInit} */
-  const init = {
-    method: "POST",
-    signal: AbortSignal.timeout(2000),
-  };
-  if (token) {
-    init.headers = { Authorization: `Bearer ${token}` };
-  }
   try {
-    await fetch(url, init);
+    await robotFetch(
+      baseUrl,
+      `/anim?name=${encodeURIComponent(animName)}`,
+      { method: "POST", signal: AbortSignal.timeout(2000) },
+      token,
+    );
   } catch {
     // Robot offline / timeout — never stall the agent.
   }

From 40d817a47ebe33d1c28823f8f8374490fae70590 Mon Sep 17 00:00:00 2001
From: shodan <mega@ioexception.at>
Date: Sun, 4 Oct 2026 13:03:16 +0200
Subject: [PATCH 10/21] refactor(scripts): load Kokoro only when say.py
 synthesizes

Argument errors and --help no longer wait for torch to load.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VYDrnWNM6nbcQ1nx8aua93
---
 scripts/say.py | 29 ++++++++++++++---------------
 1 file changed, 14 insertions(+), 15 deletions(-)

diff --git a/scripts/say.py b/scripts/say.py
index 1c1a697e..7cdfff40 100755
--- a/scripts/say.py
+++ b/scripts/say.py
@@ -16,16 +16,7 @@
 import sys
 import warnings
 
-import espeakng_loader
-
-warnings.simplefilter("ignore")
-os.environ.setdefault("HF_HUB_VERBOSITY", "error")
-
-# The bundled espeak-ng library looks for its data at the path it was built in.
-os.environ.setdefault("ESPEAK_DATA_PATH", espeakng_loader.get_data_path())
-
-import numpy  # noqa: E402
-from kokoro import KPipeline  # noqa: E402
+import numpy
 
 KOKORO_RATE = 24000
 
@@ -53,7 +44,16 @@ def parse_args():
 
 
 def synthesize(text, voice, speed):
-    """Return the audio and [word, start_ms] pairs, offset across Kokoro's chunks."""
+    """Return the audio, [word, start_ms] pairs offset across Kokoro's chunks, and the length in ms."""
+    # Imported here so argument errors and --help do not wait for torch to load.
+    import espeakng_loader
+
+    warnings.simplefilter("ignore")
+    os.environ.setdefault("HF_HUB_VERBOSITY", "error")
+    # The bundled espeak-ng library looks for its data at the path it was built in.
+    os.environ.setdefault("ESPEAK_DATA_PATH", espeakng_loader.get_data_path())
+    from kokoro import KPipeline
+
     pipeline = KPipeline(lang_code=voice[0], repo_id="hexgrad/Kokoro-82M")
     chunks = []
     words = []
@@ -69,7 +69,7 @@ def synthesize(text, voice, speed):
         chunks.append(audio)
         offset_ms += round(len(audio) * 1000 / KOKORO_RATE)
 
-    return numpy.concatenate(chunks), words
+    return numpy.concatenate(chunks), words, offset_ms
 
 
 def write_wav(audio, path, rate, plain):
@@ -80,19 +80,18 @@ def write_wav(audio, path, rate, plain):
             "-filter_complex", PLAIN_FILTER if plain else ROBOT_FILTER,
             "-map", "[out]", "-ar", str(rate), "-ac", "1", "-c:a", "pcm_s16le", path,
         ],
-        input=audio.astype(numpy.float32).tobytes(),
+        input=audio.astype(numpy.float32, copy=False).tobytes(),
         check=True,
     )
 
 
 def main():
     args = parse_args()
-    audio, words = synthesize(args.text, args.voice, args.speed)
+    audio, words, duration_ms = synthesize(args.text, args.voice, args.speed)
     if not words:
         sys.exit("Kokoro produced no speech for that text")
 
     write_wav(audio, args.output, args.rate, args.plain)
-    duration_ms = round(len(audio) * 1000 / KOKORO_RATE)
     print(json.dumps({"wav": args.output, "duration_ms": duration_ms, "words": words}))
 
 

From 4571001b31f44fe29caabd8fc8075ff35a9e429c Mon Sep 17 00:00:00 2001
From: shodan <mega@ioexception.at>
Date: Sun, 4 Oct 2026 13:11:20 +0200
Subject: [PATCH 11/21] refactor(anim): run /play timelines through a Scripted
 mode and tickRobot()

A move step switches to a new Scripted animation (no motion of its own,
so servos follow their move targets) and look/open switch to a Scripted
eye mode whose pose is the scripted gaze and lids. This replaces the
player's manual-servo branch and the per-frame pose hooks in the eye
controller; only the face override remains. GET /anim reports
`scripted` while it runs, and POST /anim does not accept it.

loop() and POST /play now share tickRobot(), so a streaming clip keeps
the sleep timer, Wi-Fi and provisioning OLED running. The clip counts as
activity, so an idle robot does not fall asleep mid-clip.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VYDrnWNM6nbcQ1nx8aua93
---
 docs/api.md                                   |   8 +-
 .../skills/tiny-engineer-play/scripts/say     |   3 -
 .../skills/tiny-engineer-play/scripts/say.py  |  99 +++++++++++++++++
 scripts/say.py                                | 100 +-----------------
 src/animation.h                               |   4 +-
 src/animation/controller.cpp                  |   2 +-
 src/animation/registry.cpp                    |  12 +++
 src/animation/timeline_player.cpp             |  22 ++--
 src/animation/timeline_player.h               |   7 +-
 src/display/eyes.h                            |   8 +-
 src/display/eyes/controller.cpp               |  10 +-
 .../eyes/{script.cpp => modes/scripted.cpp}   |  43 ++++----
 src/display/eyes/modes/scripted.h             |  15 +++
 src/display/eyes/script.h                     |  15 ---
 src/display/eyes/styles/kaomoji.cpp           |   1 +
 src/hardware/rgb.cpp                          |   1 +
 src/http/play_handlers.cpp                    |  12 +--
 src/main.cpp                                  |  12 ++-
 src/robot_tick.h                              |   8 ++
 src/sleep.cpp                                 |   4 +
 src/sleep.h                                   |   2 +
 21 files changed, 204 insertions(+), 184 deletions(-)
 delete mode 100755 packages/tiny-engineer-claude-code/skills/tiny-engineer-play/scripts/say
 create mode 100755 packages/tiny-engineer-claude-code/skills/tiny-engineer-play/scripts/say.py
 mode change 100755 => 120000 scripts/say.py
 rename src/display/eyes/{script.cpp => modes/scripted.cpp} (81%)
 create mode 100644 src/display/eyes/modes/scripted.h
 delete mode 100644 src/display/eyes/script.h
 create mode 100644 src/robot_tick.h

diff --git a/docs/api.md b/docs/api.md
index dbc43a4c..970f4a21 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -455,7 +455,7 @@ curl http://tiny-engineer.local/anim
 
 | Field | Meaning |
 | --- | --- |
-| `animation` | `none`, `typing`, `reading`, `thinking`, `ring`, `welcome`, `attention`, `error`, `abort`, `dead`, `wakeup`, or `sleep` |
+| `animation` | `none`, `typing`, `reading`, `thinking`, `ring`, `welcome`, `attention`, `error`, `abort`, `dead`, `wakeup`, or `sleep`; `scripted` while a [`POST /play`](#post-play) timeline moves the joints (not accepted by `POST /anim`) |
 
 ### `POST /anim`
 
@@ -552,14 +552,14 @@ Timeline steps run in order. Only `sleep` advances the clock, so steps without a
 | --- | --- |
 | `["sleep", ms]` | Wait `ms` (0–600000) of playback |
 | `["preset", name]` | Run an animation without its sound: `none`, `typing`, `reading`, `thinking`, or `wakeup`. Drives all joints and the eyes |
-| `["move", servo, to, ms?]` | Move `head`, `neck`, `hand_left`, `hand_right`, or `body` to pose position `to` (−1 = saved min, 1 = saved max) so it arrives after `ms`. Without `ms` it moves at the maximum speed (140°/s), which also caps short durations. Stops the running preset; other joints hold where they are |
+| `["move", servo, to, ms?]` | Move `head`, `neck`, `hand_left`, `hand_right`, or `body` to pose position `to` (−1 = saved min, 1 = saved max) so it arrives after `ms`. Without `ms` it moves at the maximum speed (140°/s), which also caps short durations. Stops the running preset and switches to the `scripted` animation; other joints hold where they are and the eyes keep their mode |
 | `["eyes", mode]` | Switch the eye mode: `idle` or any `/anim` name |
 | `["look", x, y, ms?]` | Gaze offset reached after `ms`: `x` −1 screen left to 1 screen right, `y` −1 up to 1 down |
 | `["open", amount, ms?]` | Lid opening, 0 closed to 1 normal, reached after `ms` |
 | `["blink"]` | One blink |
 | `["face", name]` | Animated face from the expression library: `idle`, `happy`, `laugh`, `wink`, `curious`, `thinking`, `surprise`, `smug`, `sleepy`, `sleep`, `sad`, `cry`, `angry`, `panic`, `shy`, or `love` |
 
-`look` and `open` reshape the eyes in the current `eyes_style`; `kaomoji` ignores them. A `face` replaces the eyes until the next `look`, `open`, `eyes`, or `preset` step. `eyes` and `preset` clear all scripted eye state.
+`look` and `open` switch the eyes to a scripted mode and reshape them in the current `eyes_style`; `kaomoji` shows its idle face. A `face` replaces the eyes until the next `look`, `open`, `eyes`, or `preset` step. `eyes` and `preset` clear all scripted eye state.
 
 When the clip ends, steps that have not run are dropped. The robot returns to the continuous animation (`typing`, `reading`, `thinking`) that was running before the request, otherwise to `none`.
 
@@ -574,7 +574,7 @@ curl -X POST http://tiny-engineer.local/play \
 { "ok": true, "played_ms": 3000 }
 ```
 
-The Claude Code CLI wraps this for agents: `tiny-engineer-claude-code play clip.wav --anim '[...]'` ([integration.md](integration.md#4-claude-code-dedicated-script)). [`scripts/say.py`](../scripts/say.py) makes a speech clip in this format and prints when each word starts ([integration.md](integration.md#speech-for-post-play)).
+The Claude Code CLI wraps this for agents: `tiny-engineer-claude-code play clip.wav --anim '[...]'` ([integration.md](integration.md#4-claude-code-dedicated-script)). [`scripts/say.py`](../packages/tiny-engineer-claude-code/skills/tiny-engineer-play/scripts/say.py) makes a speech clip in this format and prints when each word starts ([integration.md](integration.md#speech-for-post-play)).
 
 Errors arrive before any audio plays:
 
diff --git a/packages/tiny-engineer-claude-code/skills/tiny-engineer-play/scripts/say b/packages/tiny-engineer-claude-code/skills/tiny-engineer-play/scripts/say
deleted file mode 100755
index ba0a186d..00000000
--- a/packages/tiny-engineer-claude-code/skills/tiny-engineer-play/scripts/say
+++ /dev/null
@@ -1,3 +0,0 @@
-#!/bin/sh
-# Resolve the real path so the repo script is found when the skill directory is symlinked.
-exec "$(dirname "$(readlink -f "$0")")/../../../../../scripts/say.py" "$@"
diff --git a/packages/tiny-engineer-claude-code/skills/tiny-engineer-play/scripts/say.py b/packages/tiny-engineer-claude-code/skills/tiny-engineer-play/scripts/say.py
new file mode 100755
index 00000000..7cdfff40
--- /dev/null
+++ b/packages/tiny-engineer-claude-code/skills/tiny-engineer-play/scripts/say.py
@@ -0,0 +1,99 @@
+#!/usr/bin/env -S uv run --script
+# /// script
+# requires-python = ">=3.10,<3.13"
+# dependencies = [
+#     "kokoro>=0.9.4",
+#     "transformers>=4.45",
+#     "en_core_web_sm @ https://github.com/explosion/spacy-models/releases/download/en_core_web_sm-3.8.0/en_core_web_sm-3.8.0-py3-none-any.whl",
+# ]
+# ///
+"""Speak text with Kokoro in the robot's voice and print word timings for a /play timeline."""
+
+import argparse
+import json
+import os
+import subprocess
+import sys
+import warnings
+
+import numpy
+
+KOKORO_RATE = 24000
+
+# Band-limited "can" resonance, blended with a 60 Hz ring modulator and a bitcrushed flanger.
+ROBOT_FILTER = (
+    "[0:a]highpass=f=320,lowpass=f=3400,asplit=3[a][b][c];"
+    "[a]aecho=0.8:0.7:6|11:0.45|0.3,acompressor=threshold=0.1:ratio=6[can];"
+    f"sine=f=60:r={KOKORO_RATE}[carrier];[b][carrier]amultiply,volume=2[ring];"
+    "[c]acrusher=bits=6:mode=log:aa=1:samples=2,flanger=delay=2:depth=1:speed=0.3[crush];"
+    "[can][ring][crush]amix=inputs=3:weights=1 0.6 0.7:duration=first,"
+    "loudnorm=I=-15:TP=-1:LRA=7[out]"
+)
+PLAIN_FILTER = "[0:a]loudnorm=I=-15:TP=-1:LRA=7[out]"
+
+
+def parse_args():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("text")
+    parser.add_argument("-o", "--output", default="/tmp/te-clip.wav")
+    parser.add_argument("--voice", default="am_michael", help="Kokoro voice; the first letter picks the accent (a = US, b = UK)")
+    parser.add_argument("--speed", type=float, default=1.0)
+    parser.add_argument("--rate", type=int, default=22050, help="the robot's sample rate")
+    parser.add_argument("--plain", action="store_true", help="skip the robot filter")
+    return parser.parse_args()
+
+
+def synthesize(text, voice, speed):
+    """Return the audio, [word, start_ms] pairs offset across Kokoro's chunks, and the length in ms."""
+    # Imported here so argument errors and --help do not wait for torch to load.
+    import espeakng_loader
+
+    warnings.simplefilter("ignore")
+    os.environ.setdefault("HF_HUB_VERBOSITY", "error")
+    # The bundled espeak-ng library looks for its data at the path it was built in.
+    os.environ.setdefault("ESPEAK_DATA_PATH", espeakng_loader.get_data_path())
+    from kokoro import KPipeline
+
+    pipeline = KPipeline(lang_code=voice[0], repo_id="hexgrad/Kokoro-82M")
+    chunks = []
+    words = []
+    offset_ms = 0
+
+    for result in pipeline(text, voice=voice, speed=speed):
+        audio = result.audio.numpy()
+        words += [
+            [token.text, offset_ms + round(token.start_ts * 1000)]
+            for token in result.tokens or []
+            if token.start_ts is not None and any(char.isalnum() for char in token.text)
+        ]
+        chunks.append(audio)
+        offset_ms += round(len(audio) * 1000 / KOKORO_RATE)
+
+    return numpy.concatenate(chunks), words, offset_ms
+
+
+def write_wav(audio, path, rate, plain):
+    subprocess.run(
+        [
+            "ffmpeg", "-y", "-v", "error",
+            "-f", "f32le", "-ar", str(KOKORO_RATE), "-ac", "1", "-i", "-",
+            "-filter_complex", PLAIN_FILTER if plain else ROBOT_FILTER,
+            "-map", "[out]", "-ar", str(rate), "-ac", "1", "-c:a", "pcm_s16le", path,
+        ],
+        input=audio.astype(numpy.float32, copy=False).tobytes(),
+        check=True,
+    )
+
+
+def main():
+    args = parse_args()
+    audio, words, duration_ms = synthesize(args.text, args.voice, args.speed)
+    if not words:
+        sys.exit("Kokoro produced no speech for that text")
+
+    write_wav(audio, args.output, args.rate, args.plain)
+    print(json.dumps({"wav": args.output, "duration_ms": duration_ms, "words": words}))
+
+
+if __name__ == "__main__":
+    main()
diff --git a/scripts/say.py b/scripts/say.py
deleted file mode 100755
index 7cdfff40..00000000
--- a/scripts/say.py
+++ /dev/null
@@ -1,99 +0,0 @@
-#!/usr/bin/env -S uv run --script
-# /// script
-# requires-python = ">=3.10,<3.13"
-# dependencies = [
-#     "kokoro>=0.9.4",
-#     "transformers>=4.45",
-#     "en_core_web_sm @ https://github.com/explosion/spacy-models/releases/download/en_core_web_sm-3.8.0/en_core_web_sm-3.8.0-py3-none-any.whl",
-# ]
-# ///
-"""Speak text with Kokoro in the robot's voice and print word timings for a /play timeline."""
-
-import argparse
-import json
-import os
-import subprocess
-import sys
-import warnings
-
-import numpy
-
-KOKORO_RATE = 24000
-
-# Band-limited "can" resonance, blended with a 60 Hz ring modulator and a bitcrushed flanger.
-ROBOT_FILTER = (
-    "[0:a]highpass=f=320,lowpass=f=3400,asplit=3[a][b][c];"
-    "[a]aecho=0.8:0.7:6|11:0.45|0.3,acompressor=threshold=0.1:ratio=6[can];"
-    f"sine=f=60:r={KOKORO_RATE}[carrier];[b][carrier]amultiply,volume=2[ring];"
-    "[c]acrusher=bits=6:mode=log:aa=1:samples=2,flanger=delay=2:depth=1:speed=0.3[crush];"
-    "[can][ring][crush]amix=inputs=3:weights=1 0.6 0.7:duration=first,"
-    "loudnorm=I=-15:TP=-1:LRA=7[out]"
-)
-PLAIN_FILTER = "[0:a]loudnorm=I=-15:TP=-1:LRA=7[out]"
-
-
-def parse_args():
-    parser = argparse.ArgumentParser(description=__doc__)
-    parser.add_argument("text")
-    parser.add_argument("-o", "--output", default="/tmp/te-clip.wav")
-    parser.add_argument("--voice", default="am_michael", help="Kokoro voice; the first letter picks the accent (a = US, b = UK)")
-    parser.add_argument("--speed", type=float, default=1.0)
-    parser.add_argument("--rate", type=int, default=22050, help="the robot's sample rate")
-    parser.add_argument("--plain", action="store_true", help="skip the robot filter")
-    return parser.parse_args()
-
-
-def synthesize(text, voice, speed):
-    """Return the audio, [word, start_ms] pairs offset across Kokoro's chunks, and the length in ms."""
-    # Imported here so argument errors and --help do not wait for torch to load.
-    import espeakng_loader
-
-    warnings.simplefilter("ignore")
-    os.environ.setdefault("HF_HUB_VERBOSITY", "error")
-    # The bundled espeak-ng library looks for its data at the path it was built in.
-    os.environ.setdefault("ESPEAK_DATA_PATH", espeakng_loader.get_data_path())
-    from kokoro import KPipeline
-
-    pipeline = KPipeline(lang_code=voice[0], repo_id="hexgrad/Kokoro-82M")
-    chunks = []
-    words = []
-    offset_ms = 0
-
-    for result in pipeline(text, voice=voice, speed=speed):
-        audio = result.audio.numpy()
-        words += [
-            [token.text, offset_ms + round(token.start_ts * 1000)]
-            for token in result.tokens or []
-            if token.start_ts is not None and any(char.isalnum() for char in token.text)
-        ]
-        chunks.append(audio)
-        offset_ms += round(len(audio) * 1000 / KOKORO_RATE)
-
-    return numpy.concatenate(chunks), words, offset_ms
-
-
-def write_wav(audio, path, rate, plain):
-    subprocess.run(
-        [
-            "ffmpeg", "-y", "-v", "error",
-            "-f", "f32le", "-ar", str(KOKORO_RATE), "-ac", "1", "-i", "-",
-            "-filter_complex", PLAIN_FILTER if plain else ROBOT_FILTER,
-            "-map", "[out]", "-ar", str(rate), "-ac", "1", "-c:a", "pcm_s16le", path,
-        ],
-        input=audio.astype(numpy.float32, copy=False).tobytes(),
-        check=True,
-    )
-
-
-def main():
-    args = parse_args()
-    audio, words, duration_ms = synthesize(args.text, args.voice, args.speed)
-    if not words:
-        sys.exit("Kokoro produced no speech for that text")
-
-    write_wav(audio, args.output, args.rate, args.plain)
-    print(json.dumps({"wav": args.output, "duration_ms": duration_ms, "words": words}))
-
-
-if __name__ == "__main__":
-    main()
diff --git a/scripts/say.py b/scripts/say.py
new file mode 120000
index 00000000..415fc4af
--- /dev/null
+++ b/scripts/say.py
@@ -0,0 +1 @@
+../packages/tiny-engineer-claude-code/skills/tiny-engineer-play/scripts/say.py
\ No newline at end of file
diff --git a/src/animation.h b/src/animation.h
index 9095681f..e8fbd34a 100644
--- a/src/animation.h
+++ b/src/animation.h
@@ -12,7 +12,9 @@ enum class AnimationId {
   Abort,
   Wakeup,
   Sleep,
-  Dead
+  Dead,
+  // Joints follow POST /play move steps; not selectable through /anim.
+  Scripted
 };
 
 void setAnimation(AnimationId id);
diff --git a/src/animation/controller.cpp b/src/animation/controller.cpp
index 87e7bfbd..41509568 100644
--- a/src/animation/controller.cpp
+++ b/src/animation/controller.cpp
@@ -140,7 +140,7 @@ const char* animationName(AnimationId id) {
 bool parseAnimationName(const char* name, AnimationId& out) {
   const ModeEntry* entry = modeByName(name);
 
-  if (entry == nullptr) {
+  if (entry == nullptr || entry->animId == AnimationId::Scripted) {
     return false;
   }
 
diff --git a/src/animation/registry.cpp b/src/animation/registry.cpp
index 169065ea..543d9d48 100644
--- a/src/animation/registry.cpp
+++ b/src/animation/registry.cpp
@@ -19,6 +19,7 @@
 #include "display/eyes/modes/abort.h"
 #include "display/eyes/modes/attention.h"
 #include "display/eyes/modes/dead.h"
+#include "display/eyes/modes/scripted.h"
 #include "display/eyes/modes/error.h"
 #include "display/eyes/modes/idle.h"
 #include "display/eyes/modes/reading.h"
@@ -258,6 +259,17 @@ constexpr ModeEntry kModes[] = {
     startDeadEyes,
     updateDeadEyes,
   },
+  {
+    AnimationId::Scripted,
+    EyeMode::Scripted,
+    "scripted",
+    false,
+    -1,
+    nullptr,
+    nullptr,
+    startScriptedEyes,
+    updateScriptedEyes,
+  },
 };
 
 constexpr size_t kModeCount = sizeof(kModes) / sizeof(kModes[0]);
diff --git a/src/animation/timeline_player.cpp b/src/animation/timeline_player.cpp
index ba67c59b..bdc0a643 100644
--- a/src/animation/timeline_player.cpp
+++ b/src/animation/timeline_player.cpp
@@ -10,7 +10,6 @@
 #include "animation/registry.h"
 #include "display/eyes.h"
 #include "hardware/servo_wrapper.h"
-#include "network/wifi_connect.h"
 
 namespace {
 
@@ -77,19 +76,6 @@ void TimelinePlayer::advance(uint32_t playedMs) {
   }
 }
 
-void TimelinePlayer::update() {
-  if (!manualServos_) {
-    updateAnimation();
-    return;
-  }
-
-  updateAllServos();
-
-  if (!wifiProvisioningMode()) {
-    updateEyes(millis());
-  }
-}
-
 void TimelinePlayer::finish() {
   setAnimationImmediately(animationIsContinuous(previous_) ? previous_ : AnimationId::None);
 }
@@ -97,7 +83,6 @@ void TimelinePlayer::finish() {
 void TimelinePlayer::run(const Timeline::Step& step) {
   switch (step.kind) {
     case Timeline::Kind::Preset:
-      manualServos_ = false;
       setAnimationImmediately(static_cast<AnimationId>(step.target));
       break;
 
@@ -122,7 +107,12 @@ void TimelinePlayer::run(const Timeline::Step& step) {
       break;
 
     case Timeline::Kind::Move: {
-      manualServos_ = true;
+      if (getAnimation() != AnimationId::Scripted) {
+        // Hand the joints to the script but keep whatever the eyes are doing.
+        const EyeMode eyes = eyeMode();
+        setAnimationImmediately(AnimationId::Scripted);
+        setEyeMode(eyes, millis());
+      }
       ensureAllServoOutputs();
 
       ServoWrapper& servo = servoAt(step.target);
diff --git a/src/animation/timeline_player.h b/src/animation/timeline_player.h
index 75777c1a..7a46a62c 100644
--- a/src/animation/timeline_player.h
+++ b/src/animation/timeline_player.h
@@ -5,8 +5,8 @@
 #include "animation.h"
 #include "animation/timeline.h"
 
-// Runs a Timeline against the audio playback clock while loop() is blocked by
-// the stream, then hands the robot back to the animation that was running.
+// Runs a Timeline against the audio playback clock, then hands the robot back
+// to the animation that was running.
 class TimelinePlayer {
 public:
   static const Timeline::Names& names();
@@ -14,14 +14,11 @@ class TimelinePlayer {
   explicit TimelinePlayer(Timeline timeline);
 
   void advance(uint32_t playedMs);
-  void update();
   void finish();
 
 private:
   Timeline timeline_;
   size_t next_ = 0;
-  // A move takes the joints away from the preset until the next preset step.
-  bool manualServos_ = false;
   AnimationId previous_;
 
   void run(const Timeline::Step& step);
diff --git a/src/display/eyes.h b/src/display/eyes.h
index b063f903..cb0e4c2c 100644
--- a/src/display/eyes.h
+++ b/src/display/eyes.h
@@ -20,7 +20,8 @@ enum class EyeMode {
   Error,
   Abort,
   Wakeup,
-  Dead
+  Dead,
+  Scripted
 };
 
 enum class SleepEyeResult {
@@ -40,10 +41,11 @@ void requestSleepEyeOpen(uint32_t now);
 void clearSleepEyeAnim();
 SleepEyeResult updateSleepEyes(uint32_t now);
 
-// Also clears the scripted overrides below.
+// Also clears a scripted face.
 void setEyeMode(EyeMode mode, uint32_t now);
+EyeMode eyeMode();
 
-// Scripted overrides for POST /play timelines. x/y and amount are -1..1 and 0..1.
+// POST /play timeline steps. look and open switch to EyeMode::Scripted; x/y are -1..1, amount 0..1.
 void eyesLookAt(float x, float y, uint32_t durationMs, uint32_t now);
 void eyesSetOpen(float amount, uint32_t durationMs, uint32_t now);
 void eyesBlink(uint32_t now);
diff --git a/src/display/eyes/controller.cpp b/src/display/eyes/controller.cpp
index 31ea4561..4e0c7b44 100644
--- a/src/display/eyes/controller.cpp
+++ b/src/display/eyes/controller.cpp
@@ -14,7 +14,7 @@
 #include "display/eyes/core/impact.h"
 #include "display/eyes/core/internal.h"
 #include "display/eyes/core/util.h"
-#include "display/eyes/script.h"
+#include "display/eyes/modes/scripted.h"
 #include "display/eyes/styles/eye_style.h"
 #include "display/eyes/styles/kaomoji.h"
 #include "settings/settings.h"
@@ -59,7 +59,7 @@ EyeStyleSleepPhase currentSleepPhase() {
 void updateModePose(uint32_t now) {
   const ModeEntry* entry = modeByEyeMode(g_eyeMode);
 
-  if (!eyes::applyScriptPose(g_leftEye, g_rightEye, now) && entry->updateEyes != nullptr) {
+  if (entry->updateEyes != nullptr) {
     entry->updateEyes(now);
   }
 
@@ -184,8 +184,12 @@ void setEyesRunning(bool active) {
 
 }  // namespace eyes
 
+EyeMode eyeMode() {
+  return g_eyeMode;
+}
+
 void setEyeMode(EyeMode mode, uint32_t now) {
-  eyes::clearScript();
+  eyes::clearScriptFace();
   g_eyeMode = mode;
   g_modeStartedMs = now;
   resetImpactState();
diff --git a/src/display/eyes/script.cpp b/src/display/eyes/modes/scripted.cpp
similarity index 81%
rename from src/display/eyes/script.cpp
rename to src/display/eyes/modes/scripted.cpp
index 0de15208..98f81e58 100644
--- a/src/display/eyes/script.cpp
+++ b/src/display/eyes/modes/scripted.cpp
@@ -1,6 +1,7 @@
-#include "display/eyes/script.h"
+#include "display/eyes/modes/scripted.h"
 
 #include "animation/util.h"
+#include "display/eyes.h"
 #include "display/eyes/core/blink.h"
 #include "display/eyes/core/constants.h"
 #include "display/eyes/core/internal.h"
@@ -19,7 +20,6 @@ anim::EasedMove g_lookX = {};
 anim::EasedMove g_lookY = {};
 anim::EasedMove g_open = {1.0f, 1.0f, 0, 0, false};
 
-bool g_posing = false;
 bool g_faceShowing = false;
 expressions::Expression g_face = expressions::Expression::Idle;
 uint32_t g_faceStartedMs = 0;
@@ -36,22 +36,33 @@ Eye scriptedEye(const Eye& base, uint32_t now) {
   return eye;
 }
 
-void beginPosing() {
-  g_posing = true;
-  g_faceShowing = false;
-  eyes::requestForceRedraw();
+void enterScriptedEyes(uint32_t now) {
+  if (eyes::currentEyeMode() != EyeMode::Scripted) {
+    setEyeMode(EyeMode::Scripted, now);
+  }
 }
 
 }  // namespace
 
+void startScriptedEyes(uint32_t /*now*/) {
+  g_lookX = {};
+  g_lookY = {};
+  g_open = {1.0f, 1.0f, 0, 0, false};
+}
+
+void updateScriptedEyes(uint32_t now) {
+  mutableLeftEye() = scriptedEye(eyes::DEFAULT_LEFT, now);
+  mutableRightEye() = scriptedEye(eyes::DEFAULT_RIGHT, now);
+}
+
 void eyesLookAt(float x, float y, uint32_t durationMs, uint32_t now) {
-  beginPosing();
+  enterScriptedEyes(now);
   retarget(g_lookX, x, durationMs, now);
   retarget(g_lookY, y, durationMs, now);
 }
 
 void eyesSetOpen(float amount, uint32_t durationMs, uint32_t now) {
-  beginPosing();
+  enterScriptedEyes(now);
   retarget(g_open, amount, durationMs, now);
 }
 
@@ -69,16 +80,6 @@ void eyesShowFace(uint8_t expression, uint32_t now) {
 
 namespace eyes {
 
-bool applyScriptPose(Eye& left, Eye& right, uint32_t now) {
-  if (!g_posing) {
-    return false;
-  }
-
-  left = scriptedEye(DEFAULT_LEFT, now);
-  right = scriptedEye(DEFAULT_RIGHT, now);
-  return true;
-}
-
 bool drawScriptFace(uint32_t now) {
   if (!g_faceShowing) {
     return false;
@@ -96,11 +97,7 @@ bool drawScriptFace(uint32_t now) {
   return true;
 }
 
-void clearScript() {
-  g_lookX = {0.0f, 0.0f, 0, 0, false};
-  g_lookY = {0.0f, 0.0f, 0, 0, false};
-  g_open = {1.0f, 1.0f, 0, 0, false};
-  g_posing = false;
+void clearScriptFace() {
   g_faceShowing = false;
 }
 
diff --git a/src/display/eyes/modes/scripted.h b/src/display/eyes/modes/scripted.h
new file mode 100644
index 00000000..6cca11d6
--- /dev/null
+++ b/src/display/eyes/modes/scripted.h
@@ -0,0 +1,15 @@
+#pragma once
+
+#include <stdint.h>
+
+// EyeMode::Scripted: gaze and lids driven by POST /play look/open steps.
+void startScriptedEyes(uint32_t now);
+void updateScriptedEyes(uint32_t now);
+
+namespace eyes {
+
+// A scripted face replaces the eyes in every style until the next setEyeMode().
+bool drawScriptFace(uint32_t now);
+void clearScriptFace();
+
+}  // namespace eyes
diff --git a/src/display/eyes/script.h b/src/display/eyes/script.h
deleted file mode 100644
index 5fda41ff..00000000
--- a/src/display/eyes/script.h
+++ /dev/null
@@ -1,15 +0,0 @@
-#pragma once
-
-#include <cstdint>
-
-#include "display/eyes.h"
-
-namespace eyes {
-
-// Overwrites the eye rects when a scripted look or open is active.
-bool applyScriptPose(Eye& left, Eye& right, uint32_t now);
-// Draws the scripted face, if one is showing.
-bool drawScriptFace(uint32_t now);
-void clearScript();
-
-}  // namespace eyes
diff --git a/src/display/eyes/styles/kaomoji.cpp b/src/display/eyes/styles/kaomoji.cpp
index 5c176f7d..e31094e9 100644
--- a/src/display/eyes/styles/kaomoji.cpp
+++ b/src/display/eyes/styles/kaomoji.cpp
@@ -32,6 +32,7 @@ expressions::Expression expressionFor(
 
   switch (mode) {
     case EyeMode::Idle:
+    case EyeMode::Scripted:
       return expressions::Expression::Idle;
     case EyeMode::Typing:
     case EyeMode::Thinking:
diff --git a/src/hardware/rgb.cpp b/src/hardware/rgb.cpp
index 730ceb9b..f01e42e1 100644
--- a/src/hardware/rgb.cpp
+++ b/src/hardware/rgb.cpp
@@ -112,6 +112,7 @@ void resolveAnimationTarget(AnimationId id, uint8_t& r, uint8_t& g, uint8_t& b)
     case AnimationId::Welcome:
     case AnimationId::Ring:
     case AnimationId::Wakeup:
+    case AnimationId::Scripted:
       r = RGB_ANIM_WHITE;
       g = RGB_ANIM_WHITE;
       b = RGB_ANIM_WHITE;
diff --git a/src/http/play_handlers.cpp b/src/http/play_handlers.cpp
index 42e30ca2..3e8cf800 100644
--- a/src/http/play_handlers.cpp
+++ b/src/http/play_handlers.cpp
@@ -5,21 +5,21 @@
 #include <cstdio>
 #include <optional>
 
-#include "animation.h"
 #include "animation/timeline.h"
 #include "animation/timeline_player.h"
 #include "audio/audio.h"
 #include "audio/wav_parser.h"
-#include "hardware/rgb.h"
 #include "http/json.h"
 #include "pins.h"
+#include "robot_tick.h"
+#include "sleep.h"
 #include "settings/settings.h"
 #include "serial_log.h"
 
 namespace {
 
 // One POST /play request. loop() is blocked while the body streams, so the
-// session keeps animation, eyes and LED moving between speaker writes.
+// session runs tickRobot() between speaker writes.
 class PlaySession : public WavStreamParser::Sink {
 public:
   void begin(WebServer& server) {
@@ -98,12 +98,10 @@ class PlaySession : public WavStreamParser::Sink {
 
     if (player_) {
       player_->advance(playedMs());
-      player_->update();
-    } else {
-      updateAnimation();
     }
 
-    updateRgb(millis());
+    noteActivity(millis());
+    tickRobot(millis());
   }
 
 private:
diff --git a/src/main.cpp b/src/main.cpp
index ef5846c1..d584a580 100644
--- a/src/main.cpp
+++ b/src/main.cpp
@@ -18,6 +18,7 @@
 #include "settings/settings.h"
 #include "serial_log.h"
 #include "sleep.h"
+#include "robot_tick.h"
 #include "boot/boot_loading.h"
 
 namespace {
@@ -164,14 +165,17 @@ void setup() {
   initSleep();
 }
 
-void loop() {
-  const uint32_t now = millis();
+void tickRobot(uint32_t now) {
   pollWifi();
-  pollHttpServer();
-  pollOta();
   updateProvisioningOled(now);
   updateAnimation();
   // After HTTP/anim so idle timestamp from this frame is not compared to a stale `now`.
   updateSleep(millis());
   updateRgb(now);
 }
+
+void loop() {
+  pollHttpServer();
+  pollOta();
+  tickRobot(millis());
+}
diff --git a/src/robot_tick.h b/src/robot_tick.h
new file mode 100644
index 00000000..7e77504e
--- /dev/null
+++ b/src/robot_tick.h
@@ -0,0 +1,8 @@
+#pragma once
+
+#include <cstdint>
+
+// One pass of the robot's own work (Wi-Fi, animation, eyes, sleep, LED) without
+// serving HTTP or OTA. loop() calls it, and so does POST /play while it holds
+// the server streaming a clip.
+void tickRobot(uint32_t now);
diff --git a/src/sleep.cpp b/src/sleep.cpp
index 83c615ca..fdf77112 100644
--- a/src/sleep.cpp
+++ b/src/sleep.cpp
@@ -63,6 +63,10 @@ void requestSleep(uint32_t now) {
   beginSleepClosing(now);
 }
 
+void noteActivity(uint32_t now) {
+  g_idleSinceMs = now;
+}
+
 void onAnimationApplied(AnimationId id, uint32_t now) {
   if (id == AnimationId::None) {
     g_idleSinceMs = now;
diff --git a/src/sleep.h b/src/sleep.h
index d7d7d78b..7ce7512c 100644
--- a/src/sleep.h
+++ b/src/sleep.h
@@ -8,5 +8,7 @@ void initSleep();
 void prepareSleepWakePose();
 void requestSleep(uint32_t now);
 void onAnimationApplied(AnimationId id, uint32_t now);
+// Restarts the idle countdown, e.g. while a clip plays over the idle pose.
+void noteActivity(uint32_t now);
 void updateSleep(uint32_t now);
 bool isSleeping();

From 882595aacd271a2fafcc1cbb9cc729ba1590b839 Mon Sep 17 00:00:00 2001
From: shodan <mega@ioexception.at>
Date: Sun, 4 Oct 2026 13:11:20 +0200
Subject: [PATCH 12/21] refactor(integrations): ship say.py inside the
 tiny-engineer-play skill

The skill ran say.py through a wrapper that reached outside the package,
which broke for an installed package. say.py now lives in the skill's
scripts folder and scripts/say.py is a symlink to it.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VYDrnWNM6nbcQ1nx8aua93
---
 docs/integration.md                                    |  2 +-
 .../skills/tiny-engineer-play/SKILL.md                 | 10 +++++-----
 2 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/docs/integration.md b/docs/integration.md
index af2de79b..d5c67252 100644
--- a/docs/integration.md
+++ b/docs/integration.md
@@ -107,7 +107,7 @@ More routes (tests, servo, web UI): [`api.md`](api.md).
 
 ### Speech for `POST /play`
 
-[`scripts/say.py`](../scripts/say.py) speaks a line in the robot's voice: [Kokoro](https://huggingface.co/hexgrad/Kokoro-82M) text-to-speech through a tin-can filter, written as a WAV that [`POST /play`](api.md#post-play) accepts. It needs [uv](https://docs.astral.sh/uv/) and ffmpeg. The first run installs its Python dependencies and downloads the model (about 330 MB).
+[`scripts/say.py`](../packages/tiny-engineer-claude-code/skills/tiny-engineer-play/scripts/say.py) speaks a line in the robot's voice: [Kokoro](https://huggingface.co/hexgrad/Kokoro-82M) text-to-speech through a tin-can filter, written as a WAV that [`POST /play`](api.md#post-play) accepts. The script lives in the Claude Code skill and `scripts/say.py` links to it. It needs [uv](https://docs.astral.sh/uv/) and ffmpeg. The first run installs its Python dependencies and downloads the model (about 330 MB).
 
 ```bash
 scripts/say.py "Build passed. Ship it!" -o /tmp/te-clip.wav
diff --git a/packages/tiny-engineer-claude-code/skills/tiny-engineer-play/SKILL.md b/packages/tiny-engineer-claude-code/skills/tiny-engineer-play/SKILL.md
index 4dfb5ffa..6a0d0676 100644
--- a/packages/tiny-engineer-claude-code/skills/tiny-engineer-play/SKILL.md
+++ b/packages/tiny-engineer-claude-code/skills/tiny-engineer-play/SKILL.md
@@ -15,10 +15,10 @@ It reads `TINY_ENGINEER_URL` and `TINY_ENGINEER_TOKEN` from the environment (or
 
 ## 1. Make the clip
 
-The robot accepts only 16-bit mono PCM WAV at its own sample rate. Make speech in the robot's voice with the `say` script in this skill's base directory. It needs `uv` and `ffmpeg`; the first run installs its dependencies and downloads the voice model, so allow a few minutes, and later runs take about 15 s.
+The robot accepts only 16-bit mono PCM WAV at its own sample rate. Make speech in the robot's voice with the `say.py` script in this skill's base directory. It needs `uv` and `ffmpeg`; the first run installs its dependencies and downloads the voice model, so allow a few minutes, and later runs take about 15 s.
 
 ```bash
-<base directory>/scripts/say "Build passed. Ship it!" -o /tmp/te-clip.wav
+<base directory>/scripts/say.py "Build passed. Ship it!" -o /tmp/te-clip.wav
 ```
 
 It prints the clip length and the start of every word in milliseconds:
@@ -31,7 +31,7 @@ Build the timeline from these timings.
 
 Options: `--voice bm_george` for a British voice (any Kokoro voice; the default is `am_michael`), `--speed 0.9` to slow down, `--plain` for the voice without the robot filter, `--rate N` for a robot with another sample rate.
 
-If `say` is unavailable (no `uv`), fall back to the machine's own text-to-speech and convert it. There are no word timings then, so estimate from `ffprobe` duration divided by the word count:
+If `say.py` cannot run (no `uv`), fall back to the machine's own text-to-speech and convert it. There are no word timings then, so estimate from `ffprobe` duration divided by the word count:
 
 ```bash
 espeak-ng -v en-us -s 165 -w /tmp/te-raw.wav "Build passed. Ship it!"     # Linux
@@ -46,7 +46,7 @@ For a silent performance, make silence of the right length:
 ffmpeg -y -loglevel error -f lavfi -i anullsrc=r=22050:cl=mono -t 4 -c:a pcm_s16le /tmp/te-clip.wav
 ```
 
-22050 Hz is the stock rate. If the reply is `expected 16-bit mono PCM at N Hz`, re-run `say` with `--rate N` (or the `ffmpeg` step with `-ar N`).
+22050 Hz is the stock rate. If the reply is `expected 16-bit mono PCM at N Hz`, re-run `say.py` with `--rate N` (or the `ffmpeg` step with `-ar N`).
 
 ## 2. Write the timeline
 
@@ -93,7 +93,7 @@ The sleeps add up to the target times: 175 is 200 ms before "Build", 175 + 475 =
 | Reply | Fix |
 | --- | --- |
 | `400 step N: ...` | Step `N` (0-based) is wrong: unknown servo, eye mode or face, a preset with its own sound (`ring`, `welcome`, ...), or bad numbers |
-| `415 expected 16-bit mono PCM at N Hz` | Re-run `say` with `--rate N`, or convert with `ffmpeg ... -ar N -ac 1 -c:a pcm_s16le` |
+| `415 expected 16-bit mono PCM at N Hz` | Re-run `say.py` with `--rate N`, or convert with `ffmpeg ... -ar N -ac 1 -c:a pcm_s16le` |
 | `401 unauthorized` | Set `TINY_ENGINEER_TOKEN` to the robot's `access_token` |
 | `robot unreachable` | Check `TINY_ENGINEER_URL`; the robot must be on the same network |
 

From 17d9885b0e0645e07510f8819aaa095a4d33b891 Mon Sep 17 00:00:00 2001
From: shodan <mega@ioexception.at>
Date: Sun, 4 Oct 2026 13:22:35 +0200
Subject: [PATCH 13/21] feat(integrations): perform a line with cues from one
 chordsheet string

perform.py in the tiny-engineer-play skill takes a line with cues in front
of the words they belong to, for example

  {mood: proud}[nod]Build passed. {pause: 300}[happy wave]Ship it!

It checks the string first (unknown names and bad values are reported by
column with the closest valid name), speaks each segment with Kokoro,
aligns the cues to the spoken words, compiles them into an X-Anim
timeline and sends it with the play command. Gestures return to the
mood's resting pose; {define} names reusable cue groups. --check
validates without speaking and --dry-run prints the timeline.

The parser and compiler live in chordsheet.py with no dependencies, so
scripts/test_chordsheet.py runs in CI without the speech model. say.py
now loads Kokoro once so perform.py can speak several segments.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VYDrnWNM6nbcQ1nx8aua93
---
 .github/workflows/ci.yml                      |   2 +
 AGENTS.md                                     |   2 +
 docs/integration.md                           |   9 +
 .../skills/tiny-engineer-play/SKILL.md        |  32 +-
 .../tiny-engineer-play/scripts/chordsheet.py  | 315 ++++++++++++++++++
 .../tiny-engineer-play/scripts/perform.py     |  95 ++++++
 .../skills/tiny-engineer-play/scripts/say.py  |  12 +-
 scripts/test_chordsheet.py                    |  94 ++++++
 8 files changed, 556 insertions(+), 5 deletions(-)
 create mode 100644 packages/tiny-engineer-claude-code/skills/tiny-engineer-play/scripts/chordsheet.py
 create mode 100755 packages/tiny-engineer-claude-code/skills/tiny-engineer-play/scripts/perform.py
 create mode 100644 scripts/test_chordsheet.py

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index e566ad42..1bc44cd6 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -33,6 +33,8 @@ jobs:
         run: pip install -U platformio
       - name: Audio pack tests
         run: python3 scripts/test_audio_pack.py
+      - name: Chordsheet tests
+        run: python3 scripts/test_chordsheet.py
       - name: Build firmware
         run: pio run
       - name: Build OLED expression demo
diff --git a/AGENTS.md b/AGENTS.md
index f62c4fb0..6f81febd 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -32,6 +32,8 @@ node scripts/expressions/test-assets.js
 npm test --prefix packages/tiny-engineer-cursor
 npm test --prefix packages/tiny-engineer-antigravity
 npm test --prefix packages/tiny-engineer-claude-code
+python3 scripts/test_audio_pack.py
+python3 scripts/test_chordsheet.py
 python3 scripts/check_pcb.py
 ```
 
diff --git a/docs/integration.md b/docs/integration.md
index d5c67252..8f8f8e41 100644
--- a/docs/integration.md
+++ b/docs/integration.md
@@ -119,6 +119,15 @@ scripts/say.py "Build passed. Ship it!" -o /tmp/te-clip.wav
 
 `words` holds the start of each word in milliseconds of the clip, so an agent can put a `move` or `face` step on the word it belongs to. `--voice` picks another [Kokoro voice](https://huggingface.co/hexgrad/Kokoro-82M/blob/main/VOICES.md) (default `am_michael`), `--plain` skips the filter, `--rate` matches a robot built with another sample rate.
 
+`perform.py`, next to it in the skill, takes one string with cues in front of the words they belong to, speaks it, times the cues against the words and sends it:
+
+```bash
+packages/tiny-engineer-claude-code/skills/tiny-engineer-play/scripts/perform.py \
+  "{mood: proud}[nod]Build passed. {pause: 300}[look:-1,0/200]All [look:1,0/200]tests [cheer]green."
+```
+
+The cue syntax is in the skill's [`SKILL.md`](../packages/tiny-engineer-claude-code/skills/tiny-engineer-play/SKILL.md). `--check` validates the string without speaking; `--dry-run` prints the compiled timeline instead of sending it.
+
 ---
 
 ## 2. Cursor dedicated script
diff --git a/packages/tiny-engineer-claude-code/skills/tiny-engineer-play/SKILL.md b/packages/tiny-engineer-claude-code/skills/tiny-engineer-play/SKILL.md
index 6a0d0676..9c2b8e91 100644
--- a/packages/tiny-engineer-claude-code/skills/tiny-engineer-play/SKILL.md
+++ b/packages/tiny-engineer-claude-code/skills/tiny-engineer-play/SKILL.md
@@ -5,7 +5,37 @@ description: Make the Tiny Engineer desk robot speak and perform a custom animat
 
 # Tiny Engineer: speak and perform
 
-The robot plays a WAV clip while running a timeline of moves and eye changes. Send it with the script in this skill's base directory:
+The robot plays a WAV clip while running a timeline of moves and eye changes.
+
+## Quick path: one string
+
+Write the line with cues in front of the words they belong to, and `perform.py` (in this skill's base directory) speaks it, times every cue against the speech and sends it. It needs `uv` and `ffmpeg`.
+
+```bash
+<base directory>/scripts/perform.py "{mood: proud}[nod]Build passed. {pause: 300}[look:-1,0/200]All [look:1,0/200]tests [look:0,0/150 cheer]green."
+```
+
+| Form | Meaning |
+| --- | --- |
+| `[cue cue ...]word` | Cues fire on that word; moves start 150 ms early so they land on it. A group with no word after it fires when the speech before the next pause ends |
+| `nod`, `shake`, `wave`, `wave_left`, `shrug`, `cheer`, `bounce`, `blink` | Gestures; they return to the mood's resting pose |
+| `happy`, `sad`, `wink`, ... | A bare face name (`idle`, `happy`, `laugh`, `wink`, `curious`, `thinking`, `surprise`, `smug`, `sleepy`, `sleep`, `sad`, `cry`, `angry`, `panic`, `shy`, `love`) |
+| `eyes:thinking`, `preset:typing`, `face:sleep` | Prefixed names, for eye modes, presets, and faces that share a name |
+| `head:0.5/300`, `neck`, `body`, `hand_left`, `hand_right` | Move a joint to -1..1, optional `/ms` |
+| `look:-1,0/200`, `open:0.3/200` | Gaze (x -1 left..1 right, y -1 up..1 down) and eyelids (0..1) |
+| `@+200`, `@-300` | Shift the cue before it, e.g. `[blink @+200]` |
+| `{mood: proud}` | Face plus resting head pose until the next mood: `neutral`, `happy`, `proud`, `excited`, `curious`, `thinking`, `sad`, `angry`, `shy`, `sleepy` |
+| `{pause: 600}` | Real silence between sentences (splits the speech, so intonation restarts) |
+| `{define: hype = cheer happy}` | Name a group of cues to reuse as `[hype]` |
+| `{lead: 120}` | Change how early moves start |
+
+`--check` validates the string without speaking (instant, run it first), `--dry-run` prints the clip and compiled timeline without sending. Errors name the column and the closest valid name. A face replaces the eyes, so a later `look`, `open`, `eyes` or `preset` clears it; the script warns when that happens. Spell numbers out if a cue sits on them.
+
+For full control, build the clip and timeline yourself as below.
+
+## Manual path
+
+Send a clip and timeline with the `play` script in this skill's base directory:
 
 ```bash
 <base directory>/scripts/play clip.wav --anim '<timeline json>'
diff --git a/packages/tiny-engineer-claude-code/skills/tiny-engineer-play/scripts/chordsheet.py b/packages/tiny-engineer-claude-code/skills/tiny-engineer-play/scripts/chordsheet.py
new file mode 100644
index 00000000..8b4cc9d1
--- /dev/null
+++ b/packages/tiny-engineer-claude-code/skills/tiny-engineer-play/scripts/chordsheet.py
@@ -0,0 +1,315 @@
+"""Chordsheet: a spoken line with robot cues, compiled into a POST /play timeline.
+
+    {mood: proud}[nod]Build passed. {pause: 300}[happy wave]Ship [look:-1,0/200 @+100]it!
+
+`[cues]` before a word fire on that word; `{directives}` set moods, pauses,
+named chords and the lead time. Parsing needs no speech; compiling takes the
+start of every spoken word, measured by the text-to-speech engine.
+"""
+
+import difflib
+import json
+import re
+from dataclasses import dataclass, field
+
+FACES = (
+    "idle", "happy", "laugh", "wink", "curious", "thinking", "surprise", "smug",
+    "sleepy", "sleep", "sad", "cry", "angry", "panic", "shy", "love",
+)
+EYES = ("idle", "typing", "reading", "thinking", "ring", "welcome", "attention", "error", "abort", "wakeup", "dead")
+PRESETS = ("none", "typing", "reading", "thinking", "wakeup")
+SERVOS = ("head", "neck", "hand_left", "hand_right", "body")
+
+# Hands rest down; their "lift" runs toward the other end of each hand's range.
+HAND_DOWN = {"hand_left": 1.0, "hand_right": -1.0}
+
+# Built-in gestures: (ms after the gesture starts, servo, target, move ms).
+# Head, neck and body targets are offsets from the mood's resting pose; hand targets are lift 0..2.
+GESTURES = {
+    "nod": [(0, "head", 0.45, 180), (200, "head", -0.15, 180), (400, "head", 0.0, 200)],
+    "shake": [(0, "neck", 0.5, 180), (200, "neck", -0.5, 250), (470, "neck", 0.3, 200), (690, "neck", 0.0, 200)],
+    "wave": [(0, "hand_right", 1.8, 200), (250, "hand_right", 1.3, 150), (420, "hand_right", 1.8, 150),
+             (590, "hand_right", 1.3, 150), (760, "hand_right", 0.0, 300)],
+    "wave_left": [(0, "hand_left", 1.8, 200), (250, "hand_left", 1.3, 150), (420, "hand_left", 1.8, 150),
+                  (590, "hand_left", 1.3, 150), (760, "hand_left", 0.0, 300)],
+    "shrug": [(0, "hand_left", 0.7, 200), (0, "hand_right", 0.7, 200), (0, "head", -0.2, 200),
+              (600, "hand_left", 0.0, 300), (600, "hand_right", 0.0, 300), (600, "head", 0.0, 300)],
+    "cheer": [(0, "hand_left", 2.0, 250), (0, "hand_right", 2.0, 250), (0, "head", 0.3, 250),
+              (800, "hand_left", 0.0, 400), (800, "hand_right", 0.0, 400), (800, "head", 0.0, 300)],
+    "bounce": [(0, "body", 0.3, 150), (150, "body", -0.3, 200), (350, "body", 0.0, 150)],
+}
+
+# Mood: (face or eyes step, resting head position that gestures return to).
+MOODS = {
+    "neutral": (("eyes", "idle"), 0.0),
+    "happy": (("face", "happy"), 0.2),
+    "proud": (("face", "smug"), 0.35),
+    "excited": (("face", "laugh"), 0.3),
+    "curious": (("face", "curious"), 0.1),
+    "thinking": (("eyes", "thinking"), 0.4),
+    "sad": (("face", "sad"), -0.5),
+    "angry": (("face", "angry"), -0.2),
+    "shy": (("face", "shy"), -0.3),
+    "sleepy": (("face", "sleepy"), -0.3),
+}
+
+MOOD_MOVE_MS = 400
+DEFAULT_LEAD_MS = 150
+MAX_STEPS = 256
+MAX_ANIM_BYTES = 8000
+END = None  # anchor for cues with no word after them in their segment
+
+TOKEN = re.compile(r"\[(?P<cues>[^\]]*)\]|\{(?P<directive>[^}]*)\}|(?P<text>[^\[\]{}]+)")
+CUE = re.compile(r"^(?P<name>[a-z_]+)(?::(?P<args>[^/@]+))?(?:/(?P<ms>\d+))?(?:@(?P<offset>[+-]\d+))?$")
+
+
+class SheetError(Exception):
+    def __init__(self, column, message):
+        super().__init__(f"col {column}: {message}")
+        self.column = column
+
+
+@dataclass
+class Cue:
+    column: int
+    name: str
+    args: str | None = None
+    ms: int | None = None
+    offset: int = 0
+
+
+@dataclass
+class Segment:
+    words: list = field(default_factory=list)
+    # (word index or END, cues), in sheet order.
+    anchors: list = field(default_factory=list)
+    pause_after_ms: int = 0
+
+    @property
+    def text(self):
+        return " ".join(self.words)
+
+
+def suggest(name, choices):
+    close = difflib.get_close_matches(name, choices, n=1)
+    return f"; did you mean {close[0]!r}?" if close else ""
+
+
+def parse_cue(token, column):
+    match = CUE.match(token)
+    if not match:
+        raise SheetError(column, f"cannot read cue {token!r}; expected name[:args][/ms][@+-ms]")
+    return Cue(
+        column=column,
+        name=match["name"],
+        args=match["args"],
+        ms=int(match["ms"]) if match["ms"] else None,
+        offset=int(match["offset"]) if match["offset"] else 0,
+    )
+
+
+def number(text, column, low, high):
+    try:
+        value = float(text)
+    except ValueError:
+        raise SheetError(column, f"{text!r} is not a number") from None
+    if not low <= value <= high:
+        raise SheetError(column, f"{value:g} is outside {low:g}..{high:g}")
+    return value
+
+
+class Sheet:
+    def __init__(self, segments, lead_ms):
+        self.segments = segments
+        self.lead_ms = lead_ms
+
+    @classmethod
+    def parse(cls, text):
+        defines = {}
+        lead_ms = DEFAULT_LEAD_MS
+        segments = [Segment()]
+        pending = []  # cues waiting for the next word
+
+        def flush_pending(anchor):
+            if pending:
+                segments[-1].anchors.append((anchor, list(pending)))
+                pending.clear()
+
+        for match in TOKEN.finditer(text):
+            column = match.start() + 1
+
+            if match["text"] is not None:
+                for word in match["text"].split():
+                    flush_pending(len(segments[-1].words))
+                    segments[-1].words.append(word)
+                continue
+
+            if match["cues"] is not None:
+                # "cue @+100" reads like "cue@+100": the offset belongs to the cue before it.
+                group = re.sub(r"\s+@", "@", match["cues"])
+                for token in re.finditer(r"\S+", group):
+                    cue_column = match.start("cues") + token.start() + 1
+                    pending.extend(cls._expand(parse_cue(token[0], cue_column), defines, cue_column))
+                continue
+
+            key, _, value = match["directive"].partition(":")
+            key, value = key.strip(), value.strip()
+
+            if key == "mood":
+                if value not in MOODS:
+                    raise SheetError(column, f"unknown mood {value!r}{suggest(value, MOODS)}")
+                pending.append(Cue(column=column, name="mood", args=value))
+            elif key == "pause":
+                flush_pending(END)
+                segments[-1].pause_after_ms = int(number(value, column, 0, 10000))
+                segments.append(Segment())
+            elif key == "define":
+                name, equals, body = value.partition("=")
+                name = name.strip()
+                if not equals or not re.fullmatch(r"[a-z_]+", name):
+                    raise SheetError(column, "expected {define: name = cue cue ...}")
+                defines[name] = [cue for token in body.split() for cue in cls._expand(parse_cue(token, column), defines, column)]
+            elif key == "lead":
+                lead_ms = int(number(value, column, 0, 1000))
+            else:
+                raise SheetError(column, f"unknown directive {key!r}{suggest(key, ['mood', 'pause', 'define', 'lead'])}")
+
+        flush_pending(END)
+        return cls(segments, lead_ms)
+
+    @classmethod
+    def _expand(cls, cue, defines, column):
+        if cue.name in defines and cue.args is None:
+            return [Cue(column=column, name=c.name, args=c.args, ms=c.ms, offset=c.offset + cue.offset) for c in defines[cue.name]]
+        return [cls._check(cue, defines)]
+
+    @staticmethod
+    def _check(cue, defines):
+        """Reject unknown names and bad arguments before any speech is generated."""
+        name, args, column = cue.name, cue.args, cue.column
+
+        if name in GESTURES and cue.ms is not None:
+            raise SheetError(column, f"{name} has its own timing; drop /{cue.ms}")
+        if name in GESTURES or name == "blink" or (name in FACES and args is None):
+            return cue
+        if name == "face":
+            if args not in FACES:
+                raise SheetError(column, f"unknown face {args!r}{suggest(args or '', FACES)}")
+        elif name == "eyes":
+            if args not in EYES:
+                raise SheetError(column, f"unknown eye mode {args!r}{suggest(args or '', EYES)}")
+        elif name == "preset":
+            if args not in PRESETS:
+                raise SheetError(column, f"unknown preset {args!r}{suggest(args or '', PRESETS)}")
+        elif name == "mood":
+            if args not in MOODS:
+                raise SheetError(column, f"unknown mood {args!r}{suggest(args or '', MOODS)}")
+        elif name in SERVOS:
+            number(args or "", column, -1, 1)
+        elif name == "look":
+            parts = (args or "").split(",")
+            if len(parts) != 2:
+                raise SheetError(column, "look needs x,y, e.g. look:-1,0/200")
+            for part in parts:
+                number(part, column, -1, 1)
+        elif name == "open":
+            number(args or "", column, 0, 1)
+        else:
+            known = [*GESTURES, *FACES, "blink", "face", "eyes", "preset", "mood", "look", "open", *SERVOS, *defines]
+            raise SheetError(column, f"unknown cue {name!r}{suggest(name, known)}")
+        return cue
+
+    def compile(self, timings):
+        """Build the X-Anim steps. `timings` holds (word starts in ms, duration ms) per segment."""
+        events = []  # (ms, sequence, column, step)
+        rest = {"head": 0.0, "neck": 0.0, "body": 0.0}
+        segment_start = 0
+
+        def add(ms, column, step):
+            events.append((max(0, round(ms)), len(events), column, step))
+
+        for segment, (starts, duration_ms) in zip(self.segments, timings):
+            for anchor, cues in segment.anchors:
+                at = segment_start + (duration_ms if anchor is END else starts[anchor])
+                for cue in cues:
+                    self._emit(cue, at, rest, add)
+            segment_start += duration_ms + segment.pause_after_ms
+
+        events.sort(key=lambda event: (event[0], event[1]))
+        steps, warnings = [], []
+        clock, face_column = 0, None
+
+        for ms, _, column, step in events:
+            if ms > clock:
+                steps.append(["sleep", ms - clock])
+                clock = ms
+            if step[0] == "face":
+                face_column = column
+            elif step[0] in ("look", "open", "eyes", "preset") and face_column is not None:
+                warnings.append(f"col {column}: {step[0]} clears the face set at col {face_column}")
+                face_column = None
+            steps.append(step)
+
+        if len(steps) > MAX_STEPS:
+            raise SheetError(1, f"compiles to {len(steps)} steps; the robot takes at most {MAX_STEPS}")
+        if len(json.dumps(steps, separators=(",", ":"))) > MAX_ANIM_BYTES:
+            raise SheetError(1, f"compiled timeline is over {MAX_ANIM_BYTES} bytes; use fewer cues")
+        if clock > segment_start:
+            warnings.append(f"cues run {clock - segment_start} ms past the end of the speech and will be dropped")
+        return steps, warnings
+
+    def _emit(self, cue, at, rest, add):
+        name, args, column = cue.name, cue.args, cue.column
+        start = at + cue.offset
+        moving = start - self.lead_ms
+
+        def servo_target(servo, value):
+            if servo in HAND_DOWN:
+                down = HAND_DOWN[servo]
+                return round(down - value * down, 3)
+            return round(max(-1.0, min(1.0, rest[servo] + value)), 3)
+
+        if name in GESTURES:
+            for dt, servo, value, ms in GESTURES[name]:
+                add(moving + dt, column, ["move", servo, servo_target(servo, value), ms])
+        elif name == "mood":
+            (kind, value), head = MOODS[args]
+            rest["head"] = head
+            add(start, column, [kind, value])
+            add(moving, column, ["move", "head", head, MOOD_MOVE_MS])
+        elif name == "blink":
+            add(start, column, ["blink"])
+        elif name in FACES and args is None:
+            add(start, column, ["face", name])
+        elif name in ("face", "eyes", "preset"):
+            add(start, column, [name, args])
+        elif name in SERVOS:
+            add(moving, column, ["move", name, float(args), cue.ms or 300])
+        elif name == "look":
+            x, y = (float(part) for part in args.split(","))
+            add(moving, column, ["look", x, y, cue.ms or 200])
+        elif name == "open":
+            add(moving, column, ["open", float(args), cue.ms or 200])
+
+
+def normalize(word):
+    return re.sub(r"[^0-9a-z]", "", word.lower())
+
+
+def align(sheet_words, spoken):
+    """Start ms for each sheet word, from [word, start_ms] pairs the speech engine reported."""
+    ours = [normalize(word) for word in sheet_words]
+    theirs = [normalize(word) for word, _ in spoken]
+    starts = [None] * len(ours)
+
+    for block in difflib.SequenceMatcher(a=ours, b=theirs, autojunk=False).get_matching_blocks():
+        for i in range(block.size):
+            starts[block.a + i] = spoken[block.b + i][1]
+
+    # Words the engine spoke differently take the next matched start (or the last one heard).
+    following = spoken[-1][1] if spoken else 0
+    for i in range(len(starts) - 1, -1, -1):
+        if starts[i] is None:
+            starts[i] = following
+        following = starts[i]
+    return starts
diff --git a/packages/tiny-engineer-claude-code/skills/tiny-engineer-play/scripts/perform.py b/packages/tiny-engineer-claude-code/skills/tiny-engineer-play/scripts/perform.py
new file mode 100755
index 00000000..aec93722
--- /dev/null
+++ b/packages/tiny-engineer-claude-code/skills/tiny-engineer-play/scripts/perform.py
@@ -0,0 +1,95 @@
+#!/usr/bin/env -S uv run --script
+# /// script
+# requires-python = ">=3.10,<3.13"
+# dependencies = [
+#     "kokoro>=0.9.4",
+#     "transformers>=4.45",
+#     "en_core_web_sm @ https://github.com/explosion/spacy-models/releases/download/en_core_web_sm-3.8.0/en_core_web_sm-3.8.0-py3-none-any.whl",
+# ]
+# ///
+"""Speak a chordsheet in the robot's voice and play it with its cues: one string in, one performance out."""
+
+import argparse
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+import numpy
+
+HERE = Path(__file__).resolve().parent
+sys.path.insert(0, str(HERE))
+
+import chordsheet  # noqa: E402
+import say  # noqa: E402
+
+
+def parse_args():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("sheet", nargs="?", help="the chordsheet; omit to read it from stdin")
+    parser.add_argument("-o", "--output", default="/tmp/te-perform.wav")
+    parser.add_argument("--voice", default="am_michael")
+    parser.add_argument("--speed", type=float, default=1.0)
+    parser.add_argument("--rate", type=int, default=22050, help="the robot's sample rate")
+    parser.add_argument("--plain", action="store_true", help="skip the robot filter")
+    parser.add_argument("--url", help="robot base URL (default: TINY_ENGINEER_URL)")
+    parser.add_argument("--check", action="store_true", help="only validate the sheet; no speech, nothing sent")
+    parser.add_argument("--dry-run", action="store_true", help="make the clip and timeline but do not send them")
+    return parser.parse_args()
+
+
+def speak(sheet, voice, speed):
+    """Synthesize each segment, join them with their pauses, and return the audio and per-segment timings."""
+    pipeline = say.load_pipeline(voice)
+    parts, timings = [], []
+
+    for segment in sheet.segments:
+        if segment.words:
+            audio, spoken, duration_ms = say.synthesize(pipeline, segment.text, voice, speed)
+            parts.append(audio)
+            timings.append((chordsheet.align(segment.words, spoken), duration_ms))
+        else:
+            timings.append(([], 0))
+        parts.append(numpy.zeros(round(segment.pause_after_ms * say.KOKORO_RATE / 1000), dtype=numpy.float32))
+
+    return numpy.concatenate(parts), timings
+
+
+def main():
+    args = parse_args()
+    text = args.sheet if args.sheet is not None else sys.stdin.read()
+
+    try:
+        sheet = chordsheet.Sheet.parse(text)
+    except chordsheet.SheetError as error:
+        sys.exit(str(error))
+
+    if args.check:
+        print(json.dumps({"ok": True, "segments": len(sheet.segments)}))
+        return
+
+    audio, timings = speak(sheet, args.voice, args.speed)
+    try:
+        steps, warnings = sheet.compile(timings)
+    except chordsheet.SheetError as error:
+        sys.exit(str(error))
+
+    for warning in warnings:
+        print(f"warning: {warning}", file=sys.stderr)
+
+    say.write_wav(audio, args.output, args.rate, args.plain)
+    anim = json.dumps(steps, separators=(",", ":"))
+
+    if args.dry_run:
+        duration_ms = round(len(audio) * 1000 / say.KOKORO_RATE)
+        print(json.dumps({"wav": args.output, "duration_ms": duration_ms, "anim": steps}))
+        return
+
+    command = [str(HERE / "play"), args.output, "--anim", anim]
+    if args.url:
+        command += ["--url", args.url]
+    sys.exit(subprocess.run(command, check=False).returncode)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/packages/tiny-engineer-claude-code/skills/tiny-engineer-play/scripts/say.py b/packages/tiny-engineer-claude-code/skills/tiny-engineer-play/scripts/say.py
index 7cdfff40..eca2cabc 100755
--- a/packages/tiny-engineer-claude-code/skills/tiny-engineer-play/scripts/say.py
+++ b/packages/tiny-engineer-claude-code/skills/tiny-engineer-play/scripts/say.py
@@ -43,8 +43,8 @@ def parse_args():
     return parser.parse_args()
 
 
-def synthesize(text, voice, speed):
-    """Return the audio, [word, start_ms] pairs offset across Kokoro's chunks, and the length in ms."""
+def load_pipeline(voice):
+    """Load Kokoro for `voice`; the first letter of the voice picks the language."""
     # Imported here so argument errors and --help do not wait for torch to load.
     import espeakng_loader
 
@@ -54,7 +54,11 @@ def synthesize(text, voice, speed):
     os.environ.setdefault("ESPEAK_DATA_PATH", espeakng_loader.get_data_path())
     from kokoro import KPipeline
 
-    pipeline = KPipeline(lang_code=voice[0], repo_id="hexgrad/Kokoro-82M")
+    return KPipeline(lang_code=voice[0], repo_id="hexgrad/Kokoro-82M")
+
+
+def synthesize(pipeline, text, voice, speed):
+    """Return the audio, [word, start_ms] pairs offset across Kokoro's chunks, and the length in ms."""
     chunks = []
     words = []
     offset_ms = 0
@@ -87,7 +91,7 @@ def write_wav(audio, path, rate, plain):
 
 def main():
     args = parse_args()
-    audio, words, duration_ms = synthesize(args.text, args.voice, args.speed)
+    audio, words, duration_ms = synthesize(load_pipeline(args.voice), args.text, args.voice, args.speed)
     if not words:
         sys.exit("Kokoro produced no speech for that text")
 
diff --git a/scripts/test_chordsheet.py b/scripts/test_chordsheet.py
new file mode 100644
index 00000000..ea3c8a10
--- /dev/null
+++ b/scripts/test_chordsheet.py
@@ -0,0 +1,94 @@
+"""Tests for the chordsheet parser and compiler in the tiny-engineer-play skill."""
+
+import sys
+import unittest
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent / "packages/tiny-engineer-claude-code/skills/tiny-engineer-play/scripts"))
+
+from chordsheet import Sheet, SheetError, align  # noqa: E402
+
+
+def compile_sheet(text, timings):
+    return Sheet.parse(text).compile(timings)
+
+
+class CompileTest(unittest.TestCase):
+    def test_cues_fire_on_their_word_and_moves_lead_it(self):
+        steps, _ = compile_sheet("Build [happy head:0.5/300]passed.", [([100, 600], 1000)])
+
+        self.assertEqual(steps, [["sleep", 450], ["move", "head", 0.5, 300], ["sleep", 150], ["face", "happy"]])
+
+    def test_trailing_cue_fires_at_the_end_and_pause_shifts_later_words(self):
+        steps, _ = compile_sheet("Done. [blink]{pause: 500}[wink]Bye", [([0], 800), ([200], 400)])
+
+        self.assertEqual(steps, [["sleep", 800], ["blink"], ["sleep", 700], ["face", "wink"]])
+
+    def test_gestures_return_to_the_mood_resting_pose(self):
+        steps, _ = compile_sheet("{mood: proud}Hi [nod]there", [([0, 1000], 1500)])
+        head = [step for step in steps if step[:2] == ["move", "head"]]
+
+        self.assertEqual(steps[0], ["face", "smug"])
+        self.assertEqual(head[0], ["move", "head", 0.35, 400])
+        self.assertEqual(head[-1], ["move", "head", 0.35, 200])
+
+    def test_nested_defines_and_offsets_expand(self):
+        steps, _ = compile_sheet("{define: smile = happy blink}{define: hype = smile cheer}[hype@+100]Go", [([1000], 1500)])
+
+        self.assertIn(["face", "happy"], steps)
+        self.assertIn(["blink"], steps)
+        self.assertEqual(steps[0], ["sleep", 950])
+
+    def test_a_spaced_offset_belongs_to_the_cue_before_it(self):
+        steps, _ = compile_sheet("[look:-1,0/200 @+100]Hi", [([1000], 1500)])
+
+        self.assertEqual(steps, [["sleep", 950], ["look", -1.0, 0.0, 200]])
+
+    def test_hands_lift_toward_the_opposite_end_of_their_range(self):
+        right, _ = compile_sheet("[wave]Hi", [([500], 2000)])
+        left, _ = compile_sheet("[wave_left]Hi", [([500], 2000)])
+
+        self.assertIn(["move", "hand_right", 0.8, 200], right)
+        self.assertIn(["move", "hand_left", -0.8, 200], left)
+        self.assertEqual(right[-1], ["move", "hand_right", -1.0, 300])
+
+    def test_warns_when_a_later_step_clears_the_face(self):
+        _, warnings = compile_sheet("[happy]Look [look:-1,0]left", [([0, 500], 1000)])
+
+        self.assertEqual(len(warnings), 1)
+        self.assertIn("look clears the face", warnings[0])
+
+
+class ParseErrorTest(unittest.TestCase):
+    def assertSheetError(self, text, column, fragment):
+        with self.assertRaises(SheetError) as caught:
+            Sheet.parse(text)
+        self.assertEqual(caught.exception.column, column)
+        self.assertIn(fragment, str(caught.exception))
+
+    def test_reports_unknown_names_with_a_suggestion(self):
+        self.assertSheetError("Hi [hapy]there", 5, "did you mean 'happy'")
+        self.assertSheetError("Hi [eyes:thinkin]there", 5, "did you mean 'thinking'")
+        self.assertSheetError("{mod: happy}Hi", 1, "did you mean 'mood'")
+
+    def test_points_at_the_failing_cue_inside_a_group(self):
+        self.assertSheetError("Hi [happy hed:0.2]there", 11, "did you mean 'head'")
+
+    def test_rejects_out_of_range_values_and_gesture_durations(self):
+        self.assertSheetError("[head:1.5]Hi", 2, "outside -1..1")
+        self.assertSheetError("[look:0.5]Hi", 2, "look needs x,y")
+        self.assertSheetError("[nod/300]Hi", 2, "own timing")
+
+
+class AlignTest(unittest.TestCase):
+    def test_words_spoken_differently_take_the_next_known_start(self):
+        spoken = [["It", 0], ["is", 200], ["forty-two", 400], ["percent", 900], ["done", 1500]]
+
+        self.assertEqual(align(["It", "is", "42%", "done!"], spoken), [0, 200, 1500, 1500])
+
+    def test_punctuation_only_words_follow_the_next_word(self):
+        self.assertEqual(align(["Wait", "-", "what"], [["Wait", 0], ["what", 600]]), [0, 600, 600])
+
+
+if __name__ == "__main__":
+    unittest.main()

From 3448bd2c259452e4ab74dbf5d91244e39d9c2c8c Mon Sep 17 00:00:00 2001
From: shodan <mega@ioexception.at>
Date: Sun, 4 Oct 2026 13:35:55 +0200
Subject: [PATCH 14/21] refactor(firmware): one eye-mode accessor and
 tickRobot() in its own file

eyeMode() is the single accessor for the current eye mode; the internal
duplicate is gone. tickRobot() lives in robot_tick.cpp and reads the clock
itself, so the HTTP layer no longer calls into main.cpp. Sleep resets its
idle clock only through noteActivity(), and the scripted eye state is set
only when the Scripted eye mode starts.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VYDrnWNM6nbcQ1nx8aua93
---
 src/display/eyes/controller.cpp     |  4 ----
 src/display/eyes/core/blink.cpp     |  2 +-
 src/display/eyes/core/internal.h    |  1 -
 src/display/eyes/modes/scripted.cpp |  5 +++--
 src/http/play_handlers.cpp          |  2 +-
 src/main.cpp                        | 11 +----------
 src/robot_tick.cpp                  | 19 +++++++++++++++++++
 src/robot_tick.h                    |  4 +---
 src/sleep.cpp                       |  2 +-
 9 files changed, 27 insertions(+), 23 deletions(-)
 create mode 100644 src/robot_tick.cpp

diff --git a/src/display/eyes/controller.cpp b/src/display/eyes/controller.cpp
index 4e0c7b44..ce1feae8 100644
--- a/src/display/eyes/controller.cpp
+++ b/src/display/eyes/controller.cpp
@@ -146,10 +146,6 @@ void setModeStartedMs(uint32_t ms) {
   g_modeStartedMs = ms;
 }
 
-EyeMode currentEyeMode() {
-  return g_eyeMode;
-}
-
 void setCurrentEyeMode(EyeMode mode) {
   g_eyeMode = mode;
 }
diff --git a/src/display/eyes/core/blink.cpp b/src/display/eyes/core/blink.cpp
index b69c73b3..a3d4145d 100644
--- a/src/display/eyes/core/blink.cpp
+++ b/src/display/eyes/core/blink.cpp
@@ -23,7 +23,7 @@ uint8_t g_blinksInSequence = 1;
 uint8_t g_blinksDone = 0;
 
 void scheduleNextBlink(uint32_t now) {
-  switch (eyes::currentEyeMode()) {
+  switch (eyeMode()) {
     case EyeMode::Typing:
       g_nextBlinkMs = now + anim::randRangeMs(1800, 4000);
       break;
diff --git a/src/display/eyes/core/internal.h b/src/display/eyes/core/internal.h
index 3efe2746..63e93918 100644
--- a/src/display/eyes/core/internal.h
+++ b/src/display/eyes/core/internal.h
@@ -9,7 +9,6 @@ namespace eyes {
 uint32_t modeStartedMs();
 void setModeStartedMs(uint32_t ms);
 
-EyeMode currentEyeMode();
 void setCurrentEyeMode(EyeMode mode);
 
 bool forceRedraw();
diff --git a/src/display/eyes/modes/scripted.cpp b/src/display/eyes/modes/scripted.cpp
index 98f81e58..618233c8 100644
--- a/src/display/eyes/modes/scripted.cpp
+++ b/src/display/eyes/modes/scripted.cpp
@@ -16,9 +16,10 @@ namespace expressions = tiny_engineer::expressions;
 constexpr float kLookRangeX = 16.0f;
 constexpr float kLookRangeY = 8.0f;
 
+// Set by startScriptedEyes() whenever EyeMode::Scripted begins.
 anim::EasedMove g_lookX = {};
 anim::EasedMove g_lookY = {};
-anim::EasedMove g_open = {1.0f, 1.0f, 0, 0, false};
+anim::EasedMove g_open = {};
 
 bool g_faceShowing = false;
 expressions::Expression g_face = expressions::Expression::Idle;
@@ -37,7 +38,7 @@ Eye scriptedEye(const Eye& base, uint32_t now) {
 }
 
 void enterScriptedEyes(uint32_t now) {
-  if (eyes::currentEyeMode() != EyeMode::Scripted) {
+  if (eyeMode() != EyeMode::Scripted) {
     setEyeMode(EyeMode::Scripted, now);
   }
 }
diff --git a/src/http/play_handlers.cpp b/src/http/play_handlers.cpp
index 3e8cf800..322ae50e 100644
--- a/src/http/play_handlers.cpp
+++ b/src/http/play_handlers.cpp
@@ -101,7 +101,7 @@ class PlaySession : public WavStreamParser::Sink {
     }
 
     noteActivity(millis());
-    tickRobot(millis());
+    tickRobot();
   }
 
 private:
diff --git a/src/main.cpp b/src/main.cpp
index d584a580..e97a82e1 100644
--- a/src/main.cpp
+++ b/src/main.cpp
@@ -165,17 +165,8 @@ void setup() {
   initSleep();
 }
 
-void tickRobot(uint32_t now) {
-  pollWifi();
-  updateProvisioningOled(now);
-  updateAnimation();
-  // After HTTP/anim so idle timestamp from this frame is not compared to a stale `now`.
-  updateSleep(millis());
-  updateRgb(now);
-}
-
 void loop() {
   pollHttpServer();
   pollOta();
-  tickRobot(millis());
+  tickRobot();
 }
diff --git a/src/robot_tick.cpp b/src/robot_tick.cpp
new file mode 100644
index 00000000..4fd28962
--- /dev/null
+++ b/src/robot_tick.cpp
@@ -0,0 +1,19 @@
+#include "robot_tick.h"
+
+#include <Arduino.h>
+
+#include "animation.h"
+#include "display/oled.h"
+#include "hardware/rgb.h"
+#include "network/wifi_connect.h"
+#include "sleep.h"
+
+void tickRobot() {
+  const uint32_t now = millis();
+  pollWifi();
+  updateProvisioningOled(now);
+  updateAnimation();
+  // Read again: an animation applied this tick stamps its idle time after `now`.
+  updateSleep(millis());
+  updateRgb(now);
+}
diff --git a/src/robot_tick.h b/src/robot_tick.h
index 7e77504e..57662f6e 100644
--- a/src/robot_tick.h
+++ b/src/robot_tick.h
@@ -1,8 +1,6 @@
 #pragma once
 
-#include <cstdint>
-
 // One pass of the robot's own work (Wi-Fi, animation, eyes, sleep, LED) without
 // serving HTTP or OTA. loop() calls it, and so does POST /play while it holds
 // the server streaming a clip.
-void tickRobot(uint32_t now);
+void tickRobot();
diff --git a/src/sleep.cpp b/src/sleep.cpp
index fdf77112..4ac6b516 100644
--- a/src/sleep.cpp
+++ b/src/sleep.cpp
@@ -69,7 +69,7 @@ void noteActivity(uint32_t now) {
 
 void onAnimationApplied(AnimationId id, uint32_t now) {
   if (id == AnimationId::None) {
-    g_idleSinceMs = now;
+    noteActivity(now);
     return;
   }
 

From 519659b83cd1432fdacceadb7df96c1635dfc4b2 Mon Sep 17 00:00:00 2001
From: shodan <mega@ioexception.at>
Date: Sun, 4 Oct 2026 13:35:55 +0200
Subject: [PATCH 15/21] refactor(integrations): table-driven chordsheet checks
 and shared voice options

chordsheet.py validates and emits named and numeric cues from two tables
instead of one branch per cue, wave and wave_left share one shape, and a
{mood} directive goes through the same check as a mood cue. say.py and
perform.py share their voice options. Parity tests fail CI when the
Python name lists drift from the firmware or the expression manifest.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VYDrnWNM6nbcQ1nx8aua93
---
 .../tiny-engineer-play/scripts/chordsheet.py  | 63 ++++++++-----------
 .../tiny-engineer-play/scripts/perform.py     |  5 +-
 .../skills/tiny-engineer-play/scripts/say.py  | 13 ++--
 scripts/test_chordsheet.py                    | 43 ++++++++++++-
 4 files changed, 78 insertions(+), 46 deletions(-)

diff --git a/packages/tiny-engineer-claude-code/skills/tiny-engineer-play/scripts/chordsheet.py b/packages/tiny-engineer-claude-code/skills/tiny-engineer-play/scripts/chordsheet.py
index 8b4cc9d1..e504ab31 100644
--- a/packages/tiny-engineer-claude-code/skills/tiny-engineer-play/scripts/chordsheet.py
+++ b/packages/tiny-engineer-claude-code/skills/tiny-engineer-play/scripts/chordsheet.py
@@ -23,15 +23,17 @@
 # Hands rest down; their "lift" runs toward the other end of each hand's range.
 HAND_DOWN = {"hand_left": 1.0, "hand_right": -1.0}
 
+def wave(hand):
+    return [(0, hand, 1.8, 200), (250, hand, 1.3, 150), (420, hand, 1.8, 150), (590, hand, 1.3, 150), (760, hand, 0.0, 300)]
+
+
 # Built-in gestures: (ms after the gesture starts, servo, target, move ms).
 # Head, neck and body targets are offsets from the mood's resting pose; hand targets are lift 0..2.
 GESTURES = {
     "nod": [(0, "head", 0.45, 180), (200, "head", -0.15, 180), (400, "head", 0.0, 200)],
     "shake": [(0, "neck", 0.5, 180), (200, "neck", -0.5, 250), (470, "neck", 0.3, 200), (690, "neck", 0.0, 200)],
-    "wave": [(0, "hand_right", 1.8, 200), (250, "hand_right", 1.3, 150), (420, "hand_right", 1.8, 150),
-             (590, "hand_right", 1.3, 150), (760, "hand_right", 0.0, 300)],
-    "wave_left": [(0, "hand_left", 1.8, 200), (250, "hand_left", 1.3, 150), (420, "hand_left", 1.8, 150),
-                  (590, "hand_left", 1.3, 150), (760, "hand_left", 0.0, 300)],
+    "wave": wave("hand_right"),
+    "wave_left": wave("hand_left"),
     "shrug": [(0, "hand_left", 0.7, 200), (0, "hand_right", 0.7, 200), (0, "head", -0.2, 200),
               (600, "hand_left", 0.0, 300), (600, "hand_right", 0.0, 300), (600, "head", 0.0, 300)],
     "cheer": [(0, "hand_left", 2.0, 250), (0, "hand_right", 2.0, 250), (0, "head", 0.3, 250),
@@ -53,6 +55,12 @@
     "sleepy": (("face", "sleepy"), -0.3),
 }
 
+# Named arguments: `face:sleep`, `eyes:thinking`, `preset:typing`, `mood:proud`.
+CHOICES = {"face": FACES, "eyes": EYES, "preset": PRESETS, "mood": MOODS}
+# Numeric arguments: (low, high, default move ms).
+RANGES = {**{servo: (-1, 1, 300) for servo in SERVOS}, "open": (0, 1, 200), "look": (-1, 1, 200)}
+DIRECTIVES = ("mood", "pause", "define", "lead")
+
 MOOD_MOVE_MS = 400
 DEFAULT_LEAD_MS = 150
 MAX_STEPS = 256
@@ -156,9 +164,7 @@ def flush_pending(anchor):
             key, value = key.strip(), value.strip()
 
             if key == "mood":
-                if value not in MOODS:
-                    raise SheetError(column, f"unknown mood {value!r}{suggest(value, MOODS)}")
-                pending.append(Cue(column=column, name="mood", args=value))
+                pending.append(cls._check(Cue(column=column, name="mood", args=value), defines))
             elif key == "pause":
                 flush_pending(END)
                 segments[-1].pause_after_ms = int(number(value, column, 0, 10000))
@@ -172,7 +178,7 @@ def flush_pending(anchor):
             elif key == "lead":
                 lead_ms = int(number(value, column, 0, 1000))
             else:
-                raise SheetError(column, f"unknown directive {key!r}{suggest(key, ['mood', 'pause', 'define', 'lead'])}")
+                raise SheetError(column, f"unknown directive {key!r}{suggest(key, DIRECTIVES)}")
 
         flush_pending(END)
         return cls(segments, lead_ms)
@@ -192,30 +198,18 @@ def _check(cue, defines):
             raise SheetError(column, f"{name} has its own timing; drop /{cue.ms}")
         if name in GESTURES or name == "blink" or (name in FACES and args is None):
             return cue
-        if name == "face":
-            if args not in FACES:
-                raise SheetError(column, f"unknown face {args!r}{suggest(args or '', FACES)}")
-        elif name == "eyes":
-            if args not in EYES:
-                raise SheetError(column, f"unknown eye mode {args!r}{suggest(args or '', EYES)}")
-        elif name == "preset":
-            if args not in PRESETS:
-                raise SheetError(column, f"unknown preset {args!r}{suggest(args or '', PRESETS)}")
-        elif name == "mood":
-            if args not in MOODS:
-                raise SheetError(column, f"unknown mood {args!r}{suggest(args or '', MOODS)}")
-        elif name in SERVOS:
-            number(args or "", column, -1, 1)
-        elif name == "look":
+        if name in CHOICES:
+            if args not in CHOICES[name]:
+                raise SheetError(column, f"unknown {name} {args!r}{suggest(args or '', CHOICES[name])}")
+        elif name in RANGES:
+            low, high, _ = RANGES[name]
             parts = (args or "").split(",")
-            if len(parts) != 2:
-                raise SheetError(column, "look needs x,y, e.g. look:-1,0/200")
+            if len(parts) != (2 if name == "look" else 1):
+                raise SheetError(column, "look needs x,y, e.g. look:-1,0/200" if name == "look" else f"{name} needs a value, e.g. {name}:{high}")
             for part in parts:
-                number(part, column, -1, 1)
-        elif name == "open":
-            number(args or "", column, 0, 1)
+                number(part, column, low, high)
         else:
-            known = [*GESTURES, *FACES, "blink", "face", "eyes", "preset", "mood", "look", "open", *SERVOS, *defines]
+            known = [*GESTURES, *FACES, *CHOICES, *RANGES, "blink", *defines]
             raise SheetError(column, f"unknown cue {name!r}{suggest(name, known)}")
         return cue
 
@@ -283,13 +277,10 @@ def servo_target(servo, value):
             add(start, column, ["face", name])
         elif name in ("face", "eyes", "preset"):
             add(start, column, [name, args])
-        elif name in SERVOS:
-            add(moving, column, ["move", name, float(args), cue.ms or 300])
-        elif name == "look":
-            x, y = (float(part) for part in args.split(","))
-            add(moving, column, ["look", x, y, cue.ms or 200])
-        elif name == "open":
-            add(moving, column, ["open", float(args), cue.ms or 200])
+        elif name in RANGES:
+            values = [float(part) for part in args.split(",")]
+            ms = cue.ms or RANGES[name][2]
+            add(moving, column, ["move", name, *values, ms] if name in SERVOS else [name, *values, ms])
 
 
 def normalize(word):
diff --git a/packages/tiny-engineer-claude-code/skills/tiny-engineer-play/scripts/perform.py b/packages/tiny-engineer-claude-code/skills/tiny-engineer-play/scripts/perform.py
index aec93722..50fabd63 100755
--- a/packages/tiny-engineer-claude-code/skills/tiny-engineer-play/scripts/perform.py
+++ b/packages/tiny-engineer-claude-code/skills/tiny-engineer-play/scripts/perform.py
@@ -28,10 +28,7 @@ def parse_args():
     parser = argparse.ArgumentParser(description=__doc__)
     parser.add_argument("sheet", nargs="?", help="the chordsheet; omit to read it from stdin")
     parser.add_argument("-o", "--output", default="/tmp/te-perform.wav")
-    parser.add_argument("--voice", default="am_michael")
-    parser.add_argument("--speed", type=float, default=1.0)
-    parser.add_argument("--rate", type=int, default=22050, help="the robot's sample rate")
-    parser.add_argument("--plain", action="store_true", help="skip the robot filter")
+    say.add_voice_args(parser)
     parser.add_argument("--url", help="robot base URL (default: TINY_ENGINEER_URL)")
     parser.add_argument("--check", action="store_true", help="only validate the sheet; no speech, nothing sent")
     parser.add_argument("--dry-run", action="store_true", help="make the clip and timeline but do not send them")
diff --git a/packages/tiny-engineer-claude-code/skills/tiny-engineer-play/scripts/say.py b/packages/tiny-engineer-claude-code/skills/tiny-engineer-play/scripts/say.py
index eca2cabc..e371c892 100755
--- a/packages/tiny-engineer-claude-code/skills/tiny-engineer-play/scripts/say.py
+++ b/packages/tiny-engineer-claude-code/skills/tiny-engineer-play/scripts/say.py
@@ -32,14 +32,19 @@
 PLAIN_FILTER = "[0:a]loudnorm=I=-15:TP=-1:LRA=7[out]"
 
 
-def parse_args():
-    parser = argparse.ArgumentParser(description=__doc__)
-    parser.add_argument("text")
-    parser.add_argument("-o", "--output", default="/tmp/te-clip.wav")
+def add_voice_args(parser):
+    """Voice options shared with perform.py."""
     parser.add_argument("--voice", default="am_michael", help="Kokoro voice; the first letter picks the accent (a = US, b = UK)")
     parser.add_argument("--speed", type=float, default=1.0)
     parser.add_argument("--rate", type=int, default=22050, help="the robot's sample rate")
     parser.add_argument("--plain", action="store_true", help="skip the robot filter")
+
+
+def parse_args():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("text")
+    parser.add_argument("-o", "--output", default="/tmp/te-clip.wav")
+    add_voice_args(parser)
     return parser.parse_args()
 
 
diff --git a/scripts/test_chordsheet.py b/scripts/test_chordsheet.py
index ea3c8a10..992f2e23 100644
--- a/scripts/test_chordsheet.py
+++ b/scripts/test_chordsheet.py
@@ -1,12 +1,24 @@
 """Tests for the chordsheet parser and compiler in the tiny-engineer-play skill."""
 
+import json
+import re
 import sys
 import unittest
 from pathlib import Path
 
-sys.path.insert(0, str(Path(__file__).resolve().parent.parent / "packages/tiny-engineer-claude-code/skills/tiny-engineer-play/scripts"))
+ROOT = Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(ROOT / "packages/tiny-engineer-claude-code/skills/tiny-engineer-play/scripts"))
 
-from chordsheet import Sheet, SheetError, align  # noqa: E402
+from chordsheet import (  # noqa: E402
+    EYES,
+    FACES,
+    MAX_STEPS,
+    PRESETS,
+    SERVOS,
+    Sheet,
+    SheetError,
+    align,
+)
 
 
 def compile_sheet(text, timings):
@@ -90,5 +102,32 @@ def test_punctuation_only_words_follow_the_next_word(self):
         self.assertEqual(align(["Wait", "-", "what"], [["Wait", 0], ["what", 600]]), [0, 600, 600])
 
 
+class FirmwareParityTest(unittest.TestCase):
+    """chordsheet.py ships without the repo, so it mirrors these names; keep the copies in step."""
+
+    def source(self, path):
+        return (ROOT / path).read_text()
+
+    def test_faces_match_the_expression_manifest(self):
+        manifest = json.loads(self.source("scripts/expressions/manifest.json"))
+        self.assertEqual(list(FACES), [expression["id"] for expression in manifest["expressions"]])
+
+    def test_servos_match_the_firmware(self):
+        names = re.findall(r'\{"([A-Z_]+)",\s*SERVO_', self.source("include/servos.h"))
+        self.assertEqual(list(SERVOS), [name.lower() for name in names])
+
+    def test_step_limit_matches_the_firmware(self):
+        self.assertIn(f"kMaxSteps = {MAX_STEPS};", self.source("src/animation/timeline.h"))
+
+    def test_presets_match_what_the_firmware_allows(self):
+        player = self.source("src/animation/timeline_player.cpp")
+        allowed = player[player.index("resolvePreset"):player.index("default:")]
+        self.assertEqual(sorted(PRESETS), sorted(name.lower() for name in re.findall(r"AnimationId::(\w+):", allowed)))
+
+    def test_eye_modes_are_animation_names(self):
+        names = set(re.findall(r'^    "(\w+)",$', self.source("src/animation/registry.cpp"), re.MULTILINE)) - {"scripted"}
+        self.assertLessEqual(set(EYES) - {"idle"}, names)
+
+
 if __name__ == "__main__":
     unittest.main()

From 3da1f8f6d0d1fbb82be42675c3a58c3e5f74ff78 Mon Sep 17 00:00:00 2001
From: shodan <mega@ioexception.at>
Date: Sun, 4 Oct 2026 19:22:00 +0200
Subject: [PATCH 16/21] feat(anim): add a talking animation

A continuous speaking fidget with no sound of its own: the head faces the
user just above mid and nods quickly on random beats, the neck drifts,
and the right hand gestures now and then. Its eye mode looks mostly at
the user with short glances away. LED white like the other work loops;
the kaomoji style shows the happy face.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VYDrnWNM6nbcQ1nx8aua93
---
 .github/workflows/ci.yml                      |  17 +-
 AGENTS.md                                     |   2 -
 .../src/TinyEngineerExpressions.cpp           |  10 -
 .../src/TinyEngineerExpressions.h             |   3 -
 .../tiny-engineer-claude-code/package.json    |   1 -
 .../skills/tiny-engineer-play/SKILL.md        | 130 --------
 .../tiny-engineer-play/scripts/chordsheet.py  | 306 ------------------
 .../tiny-engineer-play/scripts/perform.py     |  92 ------
 .../skills/tiny-engineer-play/scripts/play    |   3 -
 .../skills/tiny-engineer-play/scripts/say.py  | 108 -------
 scripts/say.py                                |   1 -
 scripts/test_chordsheet.py                    | 133 --------
 src/animation.h                               |   3 +-
 src/animation/constants.h                     |   5 +
 src/animation/controller.cpp                  |   6 +-
 src/animation/registry.cpp                    |  23 +-
 src/animation/talking.cpp                     |  86 +++++
 src/animation/talking.h                       |   6 +
 src/animation/timeline.cpp                    | 170 ----------
 src/animation/timeline.h                      |  61 ----
 src/animation/timeline_player.cpp             | 130 --------
 src/animation/timeline_player.h               |  25 --
 src/display/eyes.h                            |  10 +-
 src/display/eyes/controller.cpp               |  14 +-
 src/display/eyes/core/blink.cpp               |   2 +-
 src/display/eyes/core/internal.h              |   1 +
 src/display/eyes/modes/scripted.cpp           | 105 ------
 src/display/eyes/modes/scripted.h             |  15 -
 src/display/eyes/modes/talking.cpp            |  38 +++
 src/display/eyes/modes/talking.h              |   6 +
 src/display/eyes/styles/kaomoji.cpp           |  18 +-
 src/display/eyes/styles/kaomoji.h             |   4 -
 src/hardware/rgb.cpp                          |   2 +-
 src/http/http_server.cpp                      |   4 +-
 test/test_expressions/test_expressions.cpp    |  15 -
 test/test_timeline/test_timeline.cpp          | 131 --------
 36 files changed, 192 insertions(+), 1494 deletions(-)
 delete mode 100644 packages/tiny-engineer-claude-code/skills/tiny-engineer-play/SKILL.md
 delete mode 100644 packages/tiny-engineer-claude-code/skills/tiny-engineer-play/scripts/chordsheet.py
 delete mode 100755 packages/tiny-engineer-claude-code/skills/tiny-engineer-play/scripts/perform.py
 delete mode 100755 packages/tiny-engineer-claude-code/skills/tiny-engineer-play/scripts/play
 delete mode 100755 packages/tiny-engineer-claude-code/skills/tiny-engineer-play/scripts/say.py
 delete mode 120000 scripts/say.py
 delete mode 100644 scripts/test_chordsheet.py
 create mode 100644 src/animation/talking.cpp
 create mode 100644 src/animation/talking.h
 delete mode 100644 src/animation/timeline.cpp
 delete mode 100644 src/animation/timeline.h
 delete mode 100644 src/animation/timeline_player.cpp
 delete mode 100644 src/animation/timeline_player.h
 delete mode 100644 src/display/eyes/modes/scripted.cpp
 delete mode 100644 src/display/eyes/modes/scripted.h
 create mode 100644 src/display/eyes/modes/talking.cpp
 create mode 100644 src/display/eyes/modes/talking.h
 delete mode 100644 test/test_timeline/test_timeline.cpp

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 1bc44cd6..ad4f3da3 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -17,6 +17,8 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
       - uses: actions/setup-python@v5
         with:
           python-version: "3.11"
@@ -33,10 +35,21 @@ jobs:
         run: pip install -U platformio
       - name: Audio pack tests
         run: python3 scripts/test_audio_pack.py
-      - name: Chordsheet tests
-        run: python3 scripts/test_chordsheet.py
       - name: Build firmware
         run: pio run
+      - name: Build LittleFS image
+        run: pio run -t buildfs
+      - name: Upload firmware binaries
+        uses: actions/upload-artifact@v4
+        with:
+          name: firmware-${{ github.sha }}
+          path: |
+            .pio/build/esp32-c3-devkitm-1/bootloader.bin
+            .pio/build/esp32-c3-devkitm-1/partitions.bin
+            .pio/build/esp32-c3-devkitm-1/firmware.bin
+            .pio/build/esp32-c3-devkitm-1/littlefs.bin
+          retention-days: 90
+          if-no-files-found: error
       - name: Build OLED expression demo
         run: pio run -e expression-demo
       - name: Host Unity tests
diff --git a/AGENTS.md b/AGENTS.md
index 6f81febd..f62c4fb0 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -32,8 +32,6 @@ node scripts/expressions/test-assets.js
 npm test --prefix packages/tiny-engineer-cursor
 npm test --prefix packages/tiny-engineer-antigravity
 npm test --prefix packages/tiny-engineer-claude-code
-python3 scripts/test_audio_pack.py
-python3 scripts/test_chordsheet.py
 python3 scripts/check_pcb.py
 ```
 
diff --git a/lib/TinyEngineerExpressions/src/TinyEngineerExpressions.cpp b/lib/TinyEngineerExpressions/src/TinyEngineerExpressions.cpp
index 90c00fef..fce7e7bd 100644
--- a/lib/TinyEngineerExpressions/src/TinyEngineerExpressions.cpp
+++ b/lib/TinyEngineerExpressions/src/TinyEngineerExpressions.cpp
@@ -35,16 +35,6 @@ const char* name(Expression expression) {
   return index < kExpressionCount ? kNames[index] : nullptr;
 }
 
-bool fromName(const char* text, Expression& expression) {
-  for (std::size_t i = 0; text != nullptr && i < kExpressionCount; i++) {
-    if (std::strcmp(kNames[i], text) == 0) {
-      expression = static_cast<Expression>(i);
-      return true;
-    }
-  }
-  return false;
-}
-
 bool render(Expression expression, uint32_t elapsedMs,
             uint8_t* output, std::size_t outputSize) {
   const auto index = static_cast<uint8_t>(expression);
diff --git a/lib/TinyEngineerExpressions/src/TinyEngineerExpressions.h b/lib/TinyEngineerExpressions/src/TinyEngineerExpressions.h
index e5a7dcfa..aaa96967 100644
--- a/lib/TinyEngineerExpressions/src/TinyEngineerExpressions.h
+++ b/lib/TinyEngineerExpressions/src/TinyEngineerExpressions.h
@@ -53,9 +53,6 @@ constexpr uint32_t kLoopDurationMs = 3000;
 // enum values return nullptr.
 const char* name(Expression expression);
 
-// Reverse of name(); false leaves `expression` unchanged for unknown names.
-bool fromName(const char* text, Expression& expression);
-
 // Render the frame at elapsedMs since the caller selected this expression.
 // The caller owns timing, selection, and display output. Animation loops every
 // kLoopDurationMs; this function never reads a clock or accesses a display.
diff --git a/packages/tiny-engineer-claude-code/package.json b/packages/tiny-engineer-claude-code/package.json
index c1167280..03ee90c5 100644
--- a/packages/tiny-engineer-claude-code/package.json
+++ b/packages/tiny-engineer-claude-code/package.json
@@ -12,7 +12,6 @@
   },
   "files": [
     "bin",
-    "skills",
     "src"
   ],
   "engines": {
diff --git a/packages/tiny-engineer-claude-code/skills/tiny-engineer-play/SKILL.md b/packages/tiny-engineer-claude-code/skills/tiny-engineer-play/SKILL.md
deleted file mode 100644
index 9c2b8e91..00000000
--- a/packages/tiny-engineer-claude-code/skills/tiny-engineer-play/SKILL.md
+++ /dev/null
@@ -1,130 +0,0 @@
----
-name: tiny-engineer-play
-description: Make the Tiny Engineer desk robot speak and perform a custom animation (servo moves, gaze, blinks, animated faces) synced to a WAV clip, via its POST /play API. Use whenever the user asks the robot to say something, celebrate, react, wave, nod, dance, show a face or emotion, announce a result, or "tell me through the robot", and whenever they ask you to choreograph, script or test robot motion or eyes. Also use when debugging /play errors such as 415 "expected 16-bit mono PCM" or 400 "step N: ...".
----
-
-# Tiny Engineer: speak and perform
-
-The robot plays a WAV clip while running a timeline of moves and eye changes.
-
-## Quick path: one string
-
-Write the line with cues in front of the words they belong to, and `perform.py` (in this skill's base directory) speaks it, times every cue against the speech and sends it. It needs `uv` and `ffmpeg`.
-
-```bash
-<base directory>/scripts/perform.py "{mood: proud}[nod]Build passed. {pause: 300}[look:-1,0/200]All [look:1,0/200]tests [look:0,0/150 cheer]green."
-```
-
-| Form | Meaning |
-| --- | --- |
-| `[cue cue ...]word` | Cues fire on that word; moves start 150 ms early so they land on it. A group with no word after it fires when the speech before the next pause ends |
-| `nod`, `shake`, `wave`, `wave_left`, `shrug`, `cheer`, `bounce`, `blink` | Gestures; they return to the mood's resting pose |
-| `happy`, `sad`, `wink`, ... | A bare face name (`idle`, `happy`, `laugh`, `wink`, `curious`, `thinking`, `surprise`, `smug`, `sleepy`, `sleep`, `sad`, `cry`, `angry`, `panic`, `shy`, `love`) |
-| `eyes:thinking`, `preset:typing`, `face:sleep` | Prefixed names, for eye modes, presets, and faces that share a name |
-| `head:0.5/300`, `neck`, `body`, `hand_left`, `hand_right` | Move a joint to -1..1, optional `/ms` |
-| `look:-1,0/200`, `open:0.3/200` | Gaze (x -1 left..1 right, y -1 up..1 down) and eyelids (0..1) |
-| `@+200`, `@-300` | Shift the cue before it, e.g. `[blink @+200]` |
-| `{mood: proud}` | Face plus resting head pose until the next mood: `neutral`, `happy`, `proud`, `excited`, `curious`, `thinking`, `sad`, `angry`, `shy`, `sleepy` |
-| `{pause: 600}` | Real silence between sentences (splits the speech, so intonation restarts) |
-| `{define: hype = cheer happy}` | Name a group of cues to reuse as `[hype]` |
-| `{lead: 120}` | Change how early moves start |
-
-`--check` validates the string without speaking (instant, run it first), `--dry-run` prints the clip and compiled timeline without sending. Errors name the column and the closest valid name. A face replaces the eyes, so a later `look`, `open`, `eyes` or `preset` clears it; the script warns when that happens. Spell numbers out if a cue sits on them.
-
-For full control, build the clip and timeline yourself as below.
-
-## Manual path
-
-Send a clip and timeline with the `play` script in this skill's base directory:
-
-```bash
-<base directory>/scripts/play clip.wav --anim '<timeline json>'
-```
-
-It reads `TINY_ENGINEER_URL` and `TINY_ENGINEER_TOKEN` from the environment (or `--url`). It prints the robot's JSON reply after the clip has finished playing and exits 1 with the reason when anything is wrong. The robot only answers one request at a time, so keep clips short (a few seconds to about 20 s); the hooks that animate the robot during normal work wait while a clip plays.
-
-## 1. Make the clip
-
-The robot accepts only 16-bit mono PCM WAV at its own sample rate. Make speech in the robot's voice with the `say.py` script in this skill's base directory. It needs `uv` and `ffmpeg`; the first run installs its dependencies and downloads the voice model, so allow a few minutes, and later runs take about 15 s.
-
-```bash
-<base directory>/scripts/say.py "Build passed. Ship it!" -o /tmp/te-clip.wav
-```
-
-It prints the clip length and the start of every word in milliseconds:
-
-```json
-{"wav": "/tmp/te-clip.wav", "duration_ms": 2200, "words": [["Build", 375], ["passed", 650], ["Ship", 1188], ["it", 1475]]}
-```
-
-Build the timeline from these timings.
-
-Options: `--voice bm_george` for a British voice (any Kokoro voice; the default is `am_michael`), `--speed 0.9` to slow down, `--plain` for the voice without the robot filter, `--rate N` for a robot with another sample rate.
-
-If `say.py` cannot run (no `uv`), fall back to the machine's own text-to-speech and convert it. There are no word timings then, so estimate from `ffprobe` duration divided by the word count:
-
-```bash
-espeak-ng -v en-us -s 165 -w /tmp/te-raw.wav "Build passed. Ship it!"     # Linux
-say --file-format=WAVE --data-format=LEI16@22050 -o /tmp/te-raw.wav "Build passed. Ship it!"  # macOS built-in say
-ffmpeg -y -loglevel error -i /tmp/te-raw.wav -ar 22050 -ac 1 -c:a pcm_s16le /tmp/te-clip.wav
-ffprobe -v error -show_entries format=duration -of csv=p=0 /tmp/te-clip.wav
-```
-
-For a silent performance, make silence of the right length:
-
-```bash
-ffmpeg -y -loglevel error -f lavfi -i anullsrc=r=22050:cl=mono -t 4 -c:a pcm_s16le /tmp/te-clip.wav
-```
-
-22050 Hz is the stock rate. If the reply is `expected 16-bit mono PCM at N Hz`, re-run `say.py` with `--rate N` (or the `ffmpeg` step with `-ar N`).
-
-## 2. Write the timeline
-
-A JSON array of steps. Steps run in order and only `sleep` advances time, so steps with no `sleep` between them start together. Time is measured in playback, so the motion stays in sync with the audio.
-
-| Step | Effect |
-| --- | --- |
-| `["sleep", ms]` | Wait `ms` of playback |
-| `["preset", name]` | Built-in motion loop with eyes: `none` (rest), `typing`, `reading`, `thinking`, `wakeup` |
-| `["move", servo, to, ms?]` | `head` (tilt), `neck` (pan), `hand_left`, `hand_right`, `body` (rotate) to `to` in -1..1, arriving after `ms`. Stops the running preset; other joints hold |
-| `["eyes", mode]` | Eye mode: `idle`, `typing`, `reading`, `thinking`, `ring`, `welcome`, `attention`, `error`, `abort`, `wakeup`, `dead` |
-| `["look", x, y, ms?]` | Gaze: `x` -1 screen left to 1 right, `y` -1 up to 1 down |
-| `["open", amount, ms?]` | Eyelids: 0 closed, 0.3 squint, 1 normal |
-| `["blink"]` | One blink |
-| `["face", name]` | Animated face: `idle`, `happy`, `laugh`, `wink`, `curious`, `thinking`, `surprise`, `smug`, `sleepy`, `sleep`, `sad`, `cry`, `angry`, `panic`, `shy`, `love` |
-
-Positions are relative to each robot's calibrated range (-1 = saved min, 1 = saved max), so they are safe on any build. The left and right hands use opposite scales: test a hand move before relying on which way is "up".
-
-A `face` stays until the next `look`, `open`, `eyes` or `preset`. When the clip ends the robot goes back to the `typing`, `reading` or `thinking` loop it was in before, otherwise to rest.
-
-Timing speech: `sleep` takes the gap between steps, not an absolute time, so turn the word starts into differences. To land a gesture on a word, start the move 100-200 ms before that word's start so it arrives on the stressed syllable. Moves of 200-500 ms read as deliberate; under 150 ms reads as a twitch. Fill pauses between sentences (a gap of 300 ms or more between words) with a blink, a glance or a new face.
-
-## 3. Send it
-
-For the clip above, a nod that lands on "Build" (375 ms) and a happy face with a wave on "Ship" (1188 ms):
-
-```bash
-<base directory>/scripts/play /tmp/te-clip.wav --anim '[
-  ["preset","thinking"],
-  ["sleep",175], ["move","head",0.5,200],
-  ["sleep",475], ["move","head",0,300],
-  ["sleep",350], ["face","happy"], ["move","hand_right",0.8,200],
-  ["sleep",400], ["move","hand_right",0.2,250],
-  ["sleep",450], ["blink"], ["preset","none"]
-]'
-```
-
-The sleeps add up to the target times: 175 is 200 ms before "Build", 175 + 475 = 650 is "passed", 650 + 350 = 1000 is about 190 ms before "Ship".
-
-`--anim-file dance.json` reads the timeline from a file instead; pretty-printed JSON is fine either way.
-
-## Errors
-
-| Reply | Fix |
-| --- | --- |
-| `400 step N: ...` | Step `N` (0-based) is wrong: unknown servo, eye mode or face, a preset with its own sound (`ring`, `welcome`, ...), or bad numbers |
-| `415 expected 16-bit mono PCM at N Hz` | Re-run `say.py` with `--rate N`, or convert with `ffmpeg ... -ar N -ac 1 -c:a pcm_s16le` |
-| `401 unauthorized` | Set `TINY_ENGINEER_TOKEN` to the robot's `access_token` |
-| `robot unreachable` | Check `TINY_ENGINEER_URL`; the robot must be on the same network |
-
-Full API reference: `docs/api.md` (`POST /play`) in the Tiny Engineer repository.
diff --git a/packages/tiny-engineer-claude-code/skills/tiny-engineer-play/scripts/chordsheet.py b/packages/tiny-engineer-claude-code/skills/tiny-engineer-play/scripts/chordsheet.py
deleted file mode 100644
index e504ab31..00000000
--- a/packages/tiny-engineer-claude-code/skills/tiny-engineer-play/scripts/chordsheet.py
+++ /dev/null
@@ -1,306 +0,0 @@
-"""Chordsheet: a spoken line with robot cues, compiled into a POST /play timeline.
-
-    {mood: proud}[nod]Build passed. {pause: 300}[happy wave]Ship [look:-1,0/200 @+100]it!
-
-`[cues]` before a word fire on that word; `{directives}` set moods, pauses,
-named chords and the lead time. Parsing needs no speech; compiling takes the
-start of every spoken word, measured by the text-to-speech engine.
-"""
-
-import difflib
-import json
-import re
-from dataclasses import dataclass, field
-
-FACES = (
-    "idle", "happy", "laugh", "wink", "curious", "thinking", "surprise", "smug",
-    "sleepy", "sleep", "sad", "cry", "angry", "panic", "shy", "love",
-)
-EYES = ("idle", "typing", "reading", "thinking", "ring", "welcome", "attention", "error", "abort", "wakeup", "dead")
-PRESETS = ("none", "typing", "reading", "thinking", "wakeup")
-SERVOS = ("head", "neck", "hand_left", "hand_right", "body")
-
-# Hands rest down; their "lift" runs toward the other end of each hand's range.
-HAND_DOWN = {"hand_left": 1.0, "hand_right": -1.0}
-
-def wave(hand):
-    return [(0, hand, 1.8, 200), (250, hand, 1.3, 150), (420, hand, 1.8, 150), (590, hand, 1.3, 150), (760, hand, 0.0, 300)]
-
-
-# Built-in gestures: (ms after the gesture starts, servo, target, move ms).
-# Head, neck and body targets are offsets from the mood's resting pose; hand targets are lift 0..2.
-GESTURES = {
-    "nod": [(0, "head", 0.45, 180), (200, "head", -0.15, 180), (400, "head", 0.0, 200)],
-    "shake": [(0, "neck", 0.5, 180), (200, "neck", -0.5, 250), (470, "neck", 0.3, 200), (690, "neck", 0.0, 200)],
-    "wave": wave("hand_right"),
-    "wave_left": wave("hand_left"),
-    "shrug": [(0, "hand_left", 0.7, 200), (0, "hand_right", 0.7, 200), (0, "head", -0.2, 200),
-              (600, "hand_left", 0.0, 300), (600, "hand_right", 0.0, 300), (600, "head", 0.0, 300)],
-    "cheer": [(0, "hand_left", 2.0, 250), (0, "hand_right", 2.0, 250), (0, "head", 0.3, 250),
-              (800, "hand_left", 0.0, 400), (800, "hand_right", 0.0, 400), (800, "head", 0.0, 300)],
-    "bounce": [(0, "body", 0.3, 150), (150, "body", -0.3, 200), (350, "body", 0.0, 150)],
-}
-
-# Mood: (face or eyes step, resting head position that gestures return to).
-MOODS = {
-    "neutral": (("eyes", "idle"), 0.0),
-    "happy": (("face", "happy"), 0.2),
-    "proud": (("face", "smug"), 0.35),
-    "excited": (("face", "laugh"), 0.3),
-    "curious": (("face", "curious"), 0.1),
-    "thinking": (("eyes", "thinking"), 0.4),
-    "sad": (("face", "sad"), -0.5),
-    "angry": (("face", "angry"), -0.2),
-    "shy": (("face", "shy"), -0.3),
-    "sleepy": (("face", "sleepy"), -0.3),
-}
-
-# Named arguments: `face:sleep`, `eyes:thinking`, `preset:typing`, `mood:proud`.
-CHOICES = {"face": FACES, "eyes": EYES, "preset": PRESETS, "mood": MOODS}
-# Numeric arguments: (low, high, default move ms).
-RANGES = {**{servo: (-1, 1, 300) for servo in SERVOS}, "open": (0, 1, 200), "look": (-1, 1, 200)}
-DIRECTIVES = ("mood", "pause", "define", "lead")
-
-MOOD_MOVE_MS = 400
-DEFAULT_LEAD_MS = 150
-MAX_STEPS = 256
-MAX_ANIM_BYTES = 8000
-END = None  # anchor for cues with no word after them in their segment
-
-TOKEN = re.compile(r"\[(?P<cues>[^\]]*)\]|\{(?P<directive>[^}]*)\}|(?P<text>[^\[\]{}]+)")
-CUE = re.compile(r"^(?P<name>[a-z_]+)(?::(?P<args>[^/@]+))?(?:/(?P<ms>\d+))?(?:@(?P<offset>[+-]\d+))?$")
-
-
-class SheetError(Exception):
-    def __init__(self, column, message):
-        super().__init__(f"col {column}: {message}")
-        self.column = column
-
-
-@dataclass
-class Cue:
-    column: int
-    name: str
-    args: str | None = None
-    ms: int | None = None
-    offset: int = 0
-
-
-@dataclass
-class Segment:
-    words: list = field(default_factory=list)
-    # (word index or END, cues), in sheet order.
-    anchors: list = field(default_factory=list)
-    pause_after_ms: int = 0
-
-    @property
-    def text(self):
-        return " ".join(self.words)
-
-
-def suggest(name, choices):
-    close = difflib.get_close_matches(name, choices, n=1)
-    return f"; did you mean {close[0]!r}?" if close else ""
-
-
-def parse_cue(token, column):
-    match = CUE.match(token)
-    if not match:
-        raise SheetError(column, f"cannot read cue {token!r}; expected name[:args][/ms][@+-ms]")
-    return Cue(
-        column=column,
-        name=match["name"],
-        args=match["args"],
-        ms=int(match["ms"]) if match["ms"] else None,
-        offset=int(match["offset"]) if match["offset"] else 0,
-    )
-
-
-def number(text, column, low, high):
-    try:
-        value = float(text)
-    except ValueError:
-        raise SheetError(column, f"{text!r} is not a number") from None
-    if not low <= value <= high:
-        raise SheetError(column, f"{value:g} is outside {low:g}..{high:g}")
-    return value
-
-
-class Sheet:
-    def __init__(self, segments, lead_ms):
-        self.segments = segments
-        self.lead_ms = lead_ms
-
-    @classmethod
-    def parse(cls, text):
-        defines = {}
-        lead_ms = DEFAULT_LEAD_MS
-        segments = [Segment()]
-        pending = []  # cues waiting for the next word
-
-        def flush_pending(anchor):
-            if pending:
-                segments[-1].anchors.append((anchor, list(pending)))
-                pending.clear()
-
-        for match in TOKEN.finditer(text):
-            column = match.start() + 1
-
-            if match["text"] is not None:
-                for word in match["text"].split():
-                    flush_pending(len(segments[-1].words))
-                    segments[-1].words.append(word)
-                continue
-
-            if match["cues"] is not None:
-                # "cue @+100" reads like "cue@+100": the offset belongs to the cue before it.
-                group = re.sub(r"\s+@", "@", match["cues"])
-                for token in re.finditer(r"\S+", group):
-                    cue_column = match.start("cues") + token.start() + 1
-                    pending.extend(cls._expand(parse_cue(token[0], cue_column), defines, cue_column))
-                continue
-
-            key, _, value = match["directive"].partition(":")
-            key, value = key.strip(), value.strip()
-
-            if key == "mood":
-                pending.append(cls._check(Cue(column=column, name="mood", args=value), defines))
-            elif key == "pause":
-                flush_pending(END)
-                segments[-1].pause_after_ms = int(number(value, column, 0, 10000))
-                segments.append(Segment())
-            elif key == "define":
-                name, equals, body = value.partition("=")
-                name = name.strip()
-                if not equals or not re.fullmatch(r"[a-z_]+", name):
-                    raise SheetError(column, "expected {define: name = cue cue ...}")
-                defines[name] = [cue for token in body.split() for cue in cls._expand(parse_cue(token, column), defines, column)]
-            elif key == "lead":
-                lead_ms = int(number(value, column, 0, 1000))
-            else:
-                raise SheetError(column, f"unknown directive {key!r}{suggest(key, DIRECTIVES)}")
-
-        flush_pending(END)
-        return cls(segments, lead_ms)
-
-    @classmethod
-    def _expand(cls, cue, defines, column):
-        if cue.name in defines and cue.args is None:
-            return [Cue(column=column, name=c.name, args=c.args, ms=c.ms, offset=c.offset + cue.offset) for c in defines[cue.name]]
-        return [cls._check(cue, defines)]
-
-    @staticmethod
-    def _check(cue, defines):
-        """Reject unknown names and bad arguments before any speech is generated."""
-        name, args, column = cue.name, cue.args, cue.column
-
-        if name in GESTURES and cue.ms is not None:
-            raise SheetError(column, f"{name} has its own timing; drop /{cue.ms}")
-        if name in GESTURES or name == "blink" or (name in FACES and args is None):
-            return cue
-        if name in CHOICES:
-            if args not in CHOICES[name]:
-                raise SheetError(column, f"unknown {name} {args!r}{suggest(args or '', CHOICES[name])}")
-        elif name in RANGES:
-            low, high, _ = RANGES[name]
-            parts = (args or "").split(",")
-            if len(parts) != (2 if name == "look" else 1):
-                raise SheetError(column, "look needs x,y, e.g. look:-1,0/200" if name == "look" else f"{name} needs a value, e.g. {name}:{high}")
-            for part in parts:
-                number(part, column, low, high)
-        else:
-            known = [*GESTURES, *FACES, *CHOICES, *RANGES, "blink", *defines]
-            raise SheetError(column, f"unknown cue {name!r}{suggest(name, known)}")
-        return cue
-
-    def compile(self, timings):
-        """Build the X-Anim steps. `timings` holds (word starts in ms, duration ms) per segment."""
-        events = []  # (ms, sequence, column, step)
-        rest = {"head": 0.0, "neck": 0.0, "body": 0.0}
-        segment_start = 0
-
-        def add(ms, column, step):
-            events.append((max(0, round(ms)), len(events), column, step))
-
-        for segment, (starts, duration_ms) in zip(self.segments, timings):
-            for anchor, cues in segment.anchors:
-                at = segment_start + (duration_ms if anchor is END else starts[anchor])
-                for cue in cues:
-                    self._emit(cue, at, rest, add)
-            segment_start += duration_ms + segment.pause_after_ms
-
-        events.sort(key=lambda event: (event[0], event[1]))
-        steps, warnings = [], []
-        clock, face_column = 0, None
-
-        for ms, _, column, step in events:
-            if ms > clock:
-                steps.append(["sleep", ms - clock])
-                clock = ms
-            if step[0] == "face":
-                face_column = column
-            elif step[0] in ("look", "open", "eyes", "preset") and face_column is not None:
-                warnings.append(f"col {column}: {step[0]} clears the face set at col {face_column}")
-                face_column = None
-            steps.append(step)
-
-        if len(steps) > MAX_STEPS:
-            raise SheetError(1, f"compiles to {len(steps)} steps; the robot takes at most {MAX_STEPS}")
-        if len(json.dumps(steps, separators=(",", ":"))) > MAX_ANIM_BYTES:
-            raise SheetError(1, f"compiled timeline is over {MAX_ANIM_BYTES} bytes; use fewer cues")
-        if clock > segment_start:
-            warnings.append(f"cues run {clock - segment_start} ms past the end of the speech and will be dropped")
-        return steps, warnings
-
-    def _emit(self, cue, at, rest, add):
-        name, args, column = cue.name, cue.args, cue.column
-        start = at + cue.offset
-        moving = start - self.lead_ms
-
-        def servo_target(servo, value):
-            if servo in HAND_DOWN:
-                down = HAND_DOWN[servo]
-                return round(down - value * down, 3)
-            return round(max(-1.0, min(1.0, rest[servo] + value)), 3)
-
-        if name in GESTURES:
-            for dt, servo, value, ms in GESTURES[name]:
-                add(moving + dt, column, ["move", servo, servo_target(servo, value), ms])
-        elif name == "mood":
-            (kind, value), head = MOODS[args]
-            rest["head"] = head
-            add(start, column, [kind, value])
-            add(moving, column, ["move", "head", head, MOOD_MOVE_MS])
-        elif name == "blink":
-            add(start, column, ["blink"])
-        elif name in FACES and args is None:
-            add(start, column, ["face", name])
-        elif name in ("face", "eyes", "preset"):
-            add(start, column, [name, args])
-        elif name in RANGES:
-            values = [float(part) for part in args.split(",")]
-            ms = cue.ms or RANGES[name][2]
-            add(moving, column, ["move", name, *values, ms] if name in SERVOS else [name, *values, ms])
-
-
-def normalize(word):
-    return re.sub(r"[^0-9a-z]", "", word.lower())
-
-
-def align(sheet_words, spoken):
-    """Start ms for each sheet word, from [word, start_ms] pairs the speech engine reported."""
-    ours = [normalize(word) for word in sheet_words]
-    theirs = [normalize(word) for word, _ in spoken]
-    starts = [None] * len(ours)
-
-    for block in difflib.SequenceMatcher(a=ours, b=theirs, autojunk=False).get_matching_blocks():
-        for i in range(block.size):
-            starts[block.a + i] = spoken[block.b + i][1]
-
-    # Words the engine spoke differently take the next matched start (or the last one heard).
-    following = spoken[-1][1] if spoken else 0
-    for i in range(len(starts) - 1, -1, -1):
-        if starts[i] is None:
-            starts[i] = following
-        following = starts[i]
-    return starts
diff --git a/packages/tiny-engineer-claude-code/skills/tiny-engineer-play/scripts/perform.py b/packages/tiny-engineer-claude-code/skills/tiny-engineer-play/scripts/perform.py
deleted file mode 100755
index 50fabd63..00000000
--- a/packages/tiny-engineer-claude-code/skills/tiny-engineer-play/scripts/perform.py
+++ /dev/null
@@ -1,92 +0,0 @@
-#!/usr/bin/env -S uv run --script
-# /// script
-# requires-python = ">=3.10,<3.13"
-# dependencies = [
-#     "kokoro>=0.9.4",
-#     "transformers>=4.45",
-#     "en_core_web_sm @ https://github.com/explosion/spacy-models/releases/download/en_core_web_sm-3.8.0/en_core_web_sm-3.8.0-py3-none-any.whl",
-# ]
-# ///
-"""Speak a chordsheet in the robot's voice and play it with its cues: one string in, one performance out."""
-
-import argparse
-import json
-import subprocess
-import sys
-from pathlib import Path
-
-import numpy
-
-HERE = Path(__file__).resolve().parent
-sys.path.insert(0, str(HERE))
-
-import chordsheet  # noqa: E402
-import say  # noqa: E402
-
-
-def parse_args():
-    parser = argparse.ArgumentParser(description=__doc__)
-    parser.add_argument("sheet", nargs="?", help="the chordsheet; omit to read it from stdin")
-    parser.add_argument("-o", "--output", default="/tmp/te-perform.wav")
-    say.add_voice_args(parser)
-    parser.add_argument("--url", help="robot base URL (default: TINY_ENGINEER_URL)")
-    parser.add_argument("--check", action="store_true", help="only validate the sheet; no speech, nothing sent")
-    parser.add_argument("--dry-run", action="store_true", help="make the clip and timeline but do not send them")
-    return parser.parse_args()
-
-
-def speak(sheet, voice, speed):
-    """Synthesize each segment, join them with their pauses, and return the audio and per-segment timings."""
-    pipeline = say.load_pipeline(voice)
-    parts, timings = [], []
-
-    for segment in sheet.segments:
-        if segment.words:
-            audio, spoken, duration_ms = say.synthesize(pipeline, segment.text, voice, speed)
-            parts.append(audio)
-            timings.append((chordsheet.align(segment.words, spoken), duration_ms))
-        else:
-            timings.append(([], 0))
-        parts.append(numpy.zeros(round(segment.pause_after_ms * say.KOKORO_RATE / 1000), dtype=numpy.float32))
-
-    return numpy.concatenate(parts), timings
-
-
-def main():
-    args = parse_args()
-    text = args.sheet if args.sheet is not None else sys.stdin.read()
-
-    try:
-        sheet = chordsheet.Sheet.parse(text)
-    except chordsheet.SheetError as error:
-        sys.exit(str(error))
-
-    if args.check:
-        print(json.dumps({"ok": True, "segments": len(sheet.segments)}))
-        return
-
-    audio, timings = speak(sheet, args.voice, args.speed)
-    try:
-        steps, warnings = sheet.compile(timings)
-    except chordsheet.SheetError as error:
-        sys.exit(str(error))
-
-    for warning in warnings:
-        print(f"warning: {warning}", file=sys.stderr)
-
-    say.write_wav(audio, args.output, args.rate, args.plain)
-    anim = json.dumps(steps, separators=(",", ":"))
-
-    if args.dry_run:
-        duration_ms = round(len(audio) * 1000 / say.KOKORO_RATE)
-        print(json.dumps({"wav": args.output, "duration_ms": duration_ms, "anim": steps}))
-        return
-
-    command = [str(HERE / "play"), args.output, "--anim", anim]
-    if args.url:
-        command += ["--url", args.url]
-    sys.exit(subprocess.run(command, check=False).returncode)
-
-
-if __name__ == "__main__":
-    main()
diff --git a/packages/tiny-engineer-claude-code/skills/tiny-engineer-play/scripts/play b/packages/tiny-engineer-claude-code/skills/tiny-engineer-play/scripts/play
deleted file mode 100755
index a6076a61..00000000
--- a/packages/tiny-engineer-claude-code/skills/tiny-engineer-play/scripts/play
+++ /dev/null
@@ -1,3 +0,0 @@
-#!/bin/sh
-# Resolve the real path so the CLI is found when the skill directory is symlinked.
-exec node "$(dirname "$(readlink -f "$0")")/../../../bin/tiny-engineer-claude-code.js" play "$@"
diff --git a/packages/tiny-engineer-claude-code/skills/tiny-engineer-play/scripts/say.py b/packages/tiny-engineer-claude-code/skills/tiny-engineer-play/scripts/say.py
deleted file mode 100755
index e371c892..00000000
--- a/packages/tiny-engineer-claude-code/skills/tiny-engineer-play/scripts/say.py
+++ /dev/null
@@ -1,108 +0,0 @@
-#!/usr/bin/env -S uv run --script
-# /// script
-# requires-python = ">=3.10,<3.13"
-# dependencies = [
-#     "kokoro>=0.9.4",
-#     "transformers>=4.45",
-#     "en_core_web_sm @ https://github.com/explosion/spacy-models/releases/download/en_core_web_sm-3.8.0/en_core_web_sm-3.8.0-py3-none-any.whl",
-# ]
-# ///
-"""Speak text with Kokoro in the robot's voice and print word timings for a /play timeline."""
-
-import argparse
-import json
-import os
-import subprocess
-import sys
-import warnings
-
-import numpy
-
-KOKORO_RATE = 24000
-
-# Band-limited "can" resonance, blended with a 60 Hz ring modulator and a bitcrushed flanger.
-ROBOT_FILTER = (
-    "[0:a]highpass=f=320,lowpass=f=3400,asplit=3[a][b][c];"
-    "[a]aecho=0.8:0.7:6|11:0.45|0.3,acompressor=threshold=0.1:ratio=6[can];"
-    f"sine=f=60:r={KOKORO_RATE}[carrier];[b][carrier]amultiply,volume=2[ring];"
-    "[c]acrusher=bits=6:mode=log:aa=1:samples=2,flanger=delay=2:depth=1:speed=0.3[crush];"
-    "[can][ring][crush]amix=inputs=3:weights=1 0.6 0.7:duration=first,"
-    "loudnorm=I=-15:TP=-1:LRA=7[out]"
-)
-PLAIN_FILTER = "[0:a]loudnorm=I=-15:TP=-1:LRA=7[out]"
-
-
-def add_voice_args(parser):
-    """Voice options shared with perform.py."""
-    parser.add_argument("--voice", default="am_michael", help="Kokoro voice; the first letter picks the accent (a = US, b = UK)")
-    parser.add_argument("--speed", type=float, default=1.0)
-    parser.add_argument("--rate", type=int, default=22050, help="the robot's sample rate")
-    parser.add_argument("--plain", action="store_true", help="skip the robot filter")
-
-
-def parse_args():
-    parser = argparse.ArgumentParser(description=__doc__)
-    parser.add_argument("text")
-    parser.add_argument("-o", "--output", default="/tmp/te-clip.wav")
-    add_voice_args(parser)
-    return parser.parse_args()
-
-
-def load_pipeline(voice):
-    """Load Kokoro for `voice`; the first letter of the voice picks the language."""
-    # Imported here so argument errors and --help do not wait for torch to load.
-    import espeakng_loader
-
-    warnings.simplefilter("ignore")
-    os.environ.setdefault("HF_HUB_VERBOSITY", "error")
-    # The bundled espeak-ng library looks for its data at the path it was built in.
-    os.environ.setdefault("ESPEAK_DATA_PATH", espeakng_loader.get_data_path())
-    from kokoro import KPipeline
-
-    return KPipeline(lang_code=voice[0], repo_id="hexgrad/Kokoro-82M")
-
-
-def synthesize(pipeline, text, voice, speed):
-    """Return the audio, [word, start_ms] pairs offset across Kokoro's chunks, and the length in ms."""
-    chunks = []
-    words = []
-    offset_ms = 0
-
-    for result in pipeline(text, voice=voice, speed=speed):
-        audio = result.audio.numpy()
-        words += [
-            [token.text, offset_ms + round(token.start_ts * 1000)]
-            for token in result.tokens or []
-            if token.start_ts is not None and any(char.isalnum() for char in token.text)
-        ]
-        chunks.append(audio)
-        offset_ms += round(len(audio) * 1000 / KOKORO_RATE)
-
-    return numpy.concatenate(chunks), words, offset_ms
-
-
-def write_wav(audio, path, rate, plain):
-    subprocess.run(
-        [
-            "ffmpeg", "-y", "-v", "error",
-            "-f", "f32le", "-ar", str(KOKORO_RATE), "-ac", "1", "-i", "-",
-            "-filter_complex", PLAIN_FILTER if plain else ROBOT_FILTER,
-            "-map", "[out]", "-ar", str(rate), "-ac", "1", "-c:a", "pcm_s16le", path,
-        ],
-        input=audio.astype(numpy.float32, copy=False).tobytes(),
-        check=True,
-    )
-
-
-def main():
-    args = parse_args()
-    audio, words, duration_ms = synthesize(load_pipeline(args.voice), args.text, args.voice, args.speed)
-    if not words:
-        sys.exit("Kokoro produced no speech for that text")
-
-    write_wav(audio, args.output, args.rate, args.plain)
-    print(json.dumps({"wav": args.output, "duration_ms": duration_ms, "words": words}))
-
-
-if __name__ == "__main__":
-    main()
diff --git a/scripts/say.py b/scripts/say.py
deleted file mode 120000
index 415fc4af..00000000
--- a/scripts/say.py
+++ /dev/null
@@ -1 +0,0 @@
-../packages/tiny-engineer-claude-code/skills/tiny-engineer-play/scripts/say.py
\ No newline at end of file
diff --git a/scripts/test_chordsheet.py b/scripts/test_chordsheet.py
deleted file mode 100644
index 992f2e23..00000000
--- a/scripts/test_chordsheet.py
+++ /dev/null
@@ -1,133 +0,0 @@
-"""Tests for the chordsheet parser and compiler in the tiny-engineer-play skill."""
-
-import json
-import re
-import sys
-import unittest
-from pathlib import Path
-
-ROOT = Path(__file__).resolve().parent.parent
-sys.path.insert(0, str(ROOT / "packages/tiny-engineer-claude-code/skills/tiny-engineer-play/scripts"))
-
-from chordsheet import (  # noqa: E402
-    EYES,
-    FACES,
-    MAX_STEPS,
-    PRESETS,
-    SERVOS,
-    Sheet,
-    SheetError,
-    align,
-)
-
-
-def compile_sheet(text, timings):
-    return Sheet.parse(text).compile(timings)
-
-
-class CompileTest(unittest.TestCase):
-    def test_cues_fire_on_their_word_and_moves_lead_it(self):
-        steps, _ = compile_sheet("Build [happy head:0.5/300]passed.", [([100, 600], 1000)])
-
-        self.assertEqual(steps, [["sleep", 450], ["move", "head", 0.5, 300], ["sleep", 150], ["face", "happy"]])
-
-    def test_trailing_cue_fires_at_the_end_and_pause_shifts_later_words(self):
-        steps, _ = compile_sheet("Done. [blink]{pause: 500}[wink]Bye", [([0], 800), ([200], 400)])
-
-        self.assertEqual(steps, [["sleep", 800], ["blink"], ["sleep", 700], ["face", "wink"]])
-
-    def test_gestures_return_to_the_mood_resting_pose(self):
-        steps, _ = compile_sheet("{mood: proud}Hi [nod]there", [([0, 1000], 1500)])
-        head = [step for step in steps if step[:2] == ["move", "head"]]
-
-        self.assertEqual(steps[0], ["face", "smug"])
-        self.assertEqual(head[0], ["move", "head", 0.35, 400])
-        self.assertEqual(head[-1], ["move", "head", 0.35, 200])
-
-    def test_nested_defines_and_offsets_expand(self):
-        steps, _ = compile_sheet("{define: smile = happy blink}{define: hype = smile cheer}[hype@+100]Go", [([1000], 1500)])
-
-        self.assertIn(["face", "happy"], steps)
-        self.assertIn(["blink"], steps)
-        self.assertEqual(steps[0], ["sleep", 950])
-
-    def test_a_spaced_offset_belongs_to_the_cue_before_it(self):
-        steps, _ = compile_sheet("[look:-1,0/200 @+100]Hi", [([1000], 1500)])
-
-        self.assertEqual(steps, [["sleep", 950], ["look", -1.0, 0.0, 200]])
-
-    def test_hands_lift_toward_the_opposite_end_of_their_range(self):
-        right, _ = compile_sheet("[wave]Hi", [([500], 2000)])
-        left, _ = compile_sheet("[wave_left]Hi", [([500], 2000)])
-
-        self.assertIn(["move", "hand_right", 0.8, 200], right)
-        self.assertIn(["move", "hand_left", -0.8, 200], left)
-        self.assertEqual(right[-1], ["move", "hand_right", -1.0, 300])
-
-    def test_warns_when_a_later_step_clears_the_face(self):
-        _, warnings = compile_sheet("[happy]Look [look:-1,0]left", [([0, 500], 1000)])
-
-        self.assertEqual(len(warnings), 1)
-        self.assertIn("look clears the face", warnings[0])
-
-
-class ParseErrorTest(unittest.TestCase):
-    def assertSheetError(self, text, column, fragment):
-        with self.assertRaises(SheetError) as caught:
-            Sheet.parse(text)
-        self.assertEqual(caught.exception.column, column)
-        self.assertIn(fragment, str(caught.exception))
-
-    def test_reports_unknown_names_with_a_suggestion(self):
-        self.assertSheetError("Hi [hapy]there", 5, "did you mean 'happy'")
-        self.assertSheetError("Hi [eyes:thinkin]there", 5, "did you mean 'thinking'")
-        self.assertSheetError("{mod: happy}Hi", 1, "did you mean 'mood'")
-
-    def test_points_at_the_failing_cue_inside_a_group(self):
-        self.assertSheetError("Hi [happy hed:0.2]there", 11, "did you mean 'head'")
-
-    def test_rejects_out_of_range_values_and_gesture_durations(self):
-        self.assertSheetError("[head:1.5]Hi", 2, "outside -1..1")
-        self.assertSheetError("[look:0.5]Hi", 2, "look needs x,y")
-        self.assertSheetError("[nod/300]Hi", 2, "own timing")
-
-
-class AlignTest(unittest.TestCase):
-    def test_words_spoken_differently_take_the_next_known_start(self):
-        spoken = [["It", 0], ["is", 200], ["forty-two", 400], ["percent", 900], ["done", 1500]]
-
-        self.assertEqual(align(["It", "is", "42%", "done!"], spoken), [0, 200, 1500, 1500])
-
-    def test_punctuation_only_words_follow_the_next_word(self):
-        self.assertEqual(align(["Wait", "-", "what"], [["Wait", 0], ["what", 600]]), [0, 600, 600])
-
-
-class FirmwareParityTest(unittest.TestCase):
-    """chordsheet.py ships without the repo, so it mirrors these names; keep the copies in step."""
-
-    def source(self, path):
-        return (ROOT / path).read_text()
-
-    def test_faces_match_the_expression_manifest(self):
-        manifest = json.loads(self.source("scripts/expressions/manifest.json"))
-        self.assertEqual(list(FACES), [expression["id"] for expression in manifest["expressions"]])
-
-    def test_servos_match_the_firmware(self):
-        names = re.findall(r'\{"([A-Z_]+)",\s*SERVO_', self.source("include/servos.h"))
-        self.assertEqual(list(SERVOS), [name.lower() for name in names])
-
-    def test_step_limit_matches_the_firmware(self):
-        self.assertIn(f"kMaxSteps = {MAX_STEPS};", self.source("src/animation/timeline.h"))
-
-    def test_presets_match_what_the_firmware_allows(self):
-        player = self.source("src/animation/timeline_player.cpp")
-        allowed = player[player.index("resolvePreset"):player.index("default:")]
-        self.assertEqual(sorted(PRESETS), sorted(name.lower() for name in re.findall(r"AnimationId::(\w+):", allowed)))
-
-    def test_eye_modes_are_animation_names(self):
-        names = set(re.findall(r'^    "(\w+)",$', self.source("src/animation/registry.cpp"), re.MULTILINE)) - {"scripted"}
-        self.assertLessEqual(set(EYES) - {"idle"}, names)
-
-
-if __name__ == "__main__":
-    unittest.main()
diff --git a/src/animation.h b/src/animation.h
index e8fbd34a..f2ff0c66 100644
--- a/src/animation.h
+++ b/src/animation.h
@@ -13,8 +13,7 @@ enum class AnimationId {
   Wakeup,
   Sleep,
   Dead,
-  // Joints follow POST /play move steps; not selectable through /anim.
-  Scripted
+  Talking
 };
 
 void setAnimation(AnimationId id);
diff --git a/src/animation/constants.h b/src/animation/constants.h
index 57fc037d..807d21af 100644
--- a/src/animation/constants.h
+++ b/src/animation/constants.h
@@ -26,6 +26,11 @@ constexpr float TYPING_HEAD_HIGH = TYPING_HEAD_LOW + TYPING_HEAD_BAND;
 constexpr float TYPING_BODY_MID = 0.0f;
 constexpr float TYPING_NECK_MID = 0.0f;
 
+// Talking faces the user: head just above mid, nodding on emphasis, neck drifting.
+constexpr float TALKING_HEAD_MID = 1.0f / 7.0f;
+constexpr float TALKING_HEAD_NOD = 2.0f / 7.0f;
+constexpr float TALKING_NECK_SWAY = 1.0f / 6.0f;
+
 constexpr float READING_HEAD_LOW = -1.0f;
 constexpr float READING_HEAD_HIGH = READING_HEAD_LOW + READING_HEAD_BAND;
 constexpr float READING_NECK_MID = 0.0f;
diff --git a/src/animation/controller.cpp b/src/animation/controller.cpp
index 41509568..c2c6fab6 100644
--- a/src/animation/controller.cpp
+++ b/src/animation/controller.cpp
@@ -109,10 +109,6 @@ void setAnimation(AnimationId id) {
   serialLogPrintln(holdLeftMs);
 }
 
-void setAnimationImmediately(AnimationId id) {
-  applyAnimation(id, millis());
-}
-
 void finishAnimation(uint32_t nowMs) {
   applyAnimation(AnimationId::None, nowMs);
 }
@@ -140,7 +136,7 @@ const char* animationName(AnimationId id) {
 bool parseAnimationName(const char* name, AnimationId& out) {
   const ModeEntry* entry = modeByName(name);
 
-  if (entry == nullptr || entry->animId == AnimationId::Scripted) {
+  if (entry == nullptr) {
     return false;
   }
 
diff --git a/src/animation/registry.cpp b/src/animation/registry.cpp
index 543d9d48..78eb7600 100644
--- a/src/animation/registry.cpp
+++ b/src/animation/registry.cpp
@@ -9,6 +9,7 @@
 #include "animation/dead.h"
 #include "animation/error.h"
 #include "animation/reading.h"
+#include "animation/talking.h"
 #include "animation/ring.h"
 #include "animation/sleep_anim.h"
 #include "animation/thinking.h"
@@ -19,10 +20,10 @@
 #include "display/eyes/modes/abort.h"
 #include "display/eyes/modes/attention.h"
 #include "display/eyes/modes/dead.h"
-#include "display/eyes/modes/scripted.h"
 #include "display/eyes/modes/error.h"
 #include "display/eyes/modes/idle.h"
 #include "display/eyes/modes/reading.h"
+#include "display/eyes/modes/talking.h"
 #include "display/eyes/modes/ring.h"
 #include "display/eyes/modes/thinking.h"
 #include "display/eyes/modes/typing.h"
@@ -82,6 +83,10 @@ void startReadingAt(uint32_t /*nowMs*/) {
   startReading();
 }
 
+void startTalkingAt(uint32_t /*nowMs*/) {
+  startTalking();
+}
+
 void startRingAt(uint32_t /*nowMs*/) {
   startRing();
 }
@@ -260,15 +265,15 @@ constexpr ModeEntry kModes[] = {
     updateDeadEyes,
   },
   {
-    AnimationId::Scripted,
-    EyeMode::Scripted,
-    "scripted",
-    false,
+    AnimationId::Talking,
+    EyeMode::Talking,
+    "talking",
+    true,
     -1,
-    nullptr,
-    nullptr,
-    startScriptedEyes,
-    updateScriptedEyes,
+    startTalkingAt,
+    updateTalking,
+    startTalkingEyes,
+    updateTalkingEyes,
   },
 };
 
diff --git a/src/animation/talking.cpp b/src/animation/talking.cpp
new file mode 100644
index 00000000..0384fd08
--- /dev/null
+++ b/src/animation/talking.cpp
@@ -0,0 +1,86 @@
+#include <Arduino.h>
+
+#include "animation.h"
+#include "animation/constants.h"
+#include "animation/talking.h"
+#include "animation/util.h"
+#include "hardware/servo_wrapper.h"
+#include "servos.h"
+
+using anim::parkTorso;
+using anim::randRangeMs;
+using anim::randUnit;
+using anim::stopAnimServos;
+
+namespace {
+
+bool g_poseFrozen = false;
+bool g_headUp = false;
+bool g_gestureRaised = false;
+uint32_t g_headPauseUntilMs = 0;
+uint32_t g_neckNextMs = 0;
+uint32_t g_gestureNextMs = 0;
+
+void commandHeadBeat() {
+  // Quick up on the beat, slower settle, so it reads as emphasis rather than a bob.
+  g_headUp = !g_headUp;
+  const float target = g_headUp
+    ? anim::TALKING_HEAD_MID + anim::TALKING_HEAD_NOD * (0.4f + 0.6f * randUnit())
+    : anim::TALKING_HEAD_MID;
+  const float speed = g_headUp ? 45.0f + 30.0f * randUnit() : 20.0f + 15.0f * randUnit();
+  servoAt(SERVO_HEAD).setNormTarget(target, speed);
+}
+
+void commandNeckDrift() {
+  const float target = anim::TALKING_NECK_SWAY * (2.0f * randUnit() - 1.0f);
+  servoAt(SERVO_NECK).setNormTarget(target, 10.0f + 10.0f * randUnit());
+}
+
+void commandGesture() {
+  g_gestureRaised = !g_gestureRaised;
+  const float lift = g_gestureRaised ? anim::TYPING_HAND_BAND * (1.5f + 1.5f * randUnit()) : 0.0f;
+  servoAt(SERVO_HAND_RIGHT).setNormTarget(anim::TYPING_RIGHT_LOW + lift, g_gestureRaised ? 70.0f : 50.0f);
+}
+
+}  // namespace
+
+void startTalking() {
+  stopAnimServos();
+  anim::parkNonePose();
+  const uint32_t now = millis();
+  g_poseFrozen = false;
+  g_headUp = false;
+  g_gestureRaised = false;
+  g_headPauseUntilMs = now + randRangeMs(150, 350);
+  g_neckNextMs = now + randRangeMs(400, 900);
+  g_gestureNextMs = now + randRangeMs(1500, 3500);
+  servoAt(SERVO_HEAD).setNormTarget(anim::TALKING_HEAD_MID, anim::TRANSITION_TORSO_SPEED_DEG_S);
+}
+
+void updateTalking(uint32_t now) {
+  updateAllServos();
+
+  if (hasPendingAnimation() && !g_poseFrozen) {
+    g_poseFrozen = true;
+    parkTorso(anim::TRANSITION_TORSO_SPEED_DEG_S);
+  }
+
+  if (g_poseFrozen) {
+    return;
+  }
+
+  if (!servoAt(SERVO_HEAD).isMoving() && now >= g_headPauseUntilMs) {
+    commandHeadBeat();
+    g_headPauseUntilMs = now + (g_headUp ? randRangeMs(60, 160) : randRangeMs(180, 650));
+  }
+
+  if (now >= g_neckNextMs) {
+    commandNeckDrift();
+    g_neckNextMs = now + randRangeMs(900, 2200);
+  }
+
+  if (now >= g_gestureNextMs && !servoAt(SERVO_HAND_RIGHT).isMoving()) {
+    commandGesture();
+    g_gestureNextMs = now + (g_gestureRaised ? randRangeMs(500, 1100) : randRangeMs(2500, 6000));
+  }
+}
diff --git a/src/animation/talking.h b/src/animation/talking.h
new file mode 100644
index 00000000..365ce6c9
--- /dev/null
+++ b/src/animation/talking.h
@@ -0,0 +1,6 @@
+#pragma once
+
+#include <stdint.h>
+
+void startTalking();
+void updateTalking(uint32_t now);
diff --git a/src/animation/timeline.cpp b/src/animation/timeline.cpp
deleted file mode 100644
index 45f5a8f5..00000000
--- a/src/animation/timeline.cpp
+++ /dev/null
@@ -1,170 +0,0 @@
-#include "animation/timeline.h"
-
-#include <ArduinoJson.h>
-
-#include <algorithm>
-#include <cstdio>
-#include <cstring>
-#include <strings.h>
-
-#include "servos.h"
-
-namespace {
-
-bool findServo(const char* name, uint8_t& index) {
-  for (uint8_t i = 0; i < SERVO_COUNT; i++) {
-    if (strcasecmp(SERVO_SPECS[i].name, name) == 0) {
-      index = i;
-      return true;
-    }
-  }
-
-  return false;
-}
-
-bool isMs(JsonVariantConst value) {
-  return value.is<uint32_t>() && value.as<uint32_t>() <= Timeline::kMaxSleepMs;
-}
-
-bool isOptionalMs(JsonVariantConst value) {
-  return value.isNull() || isMs(value);
-}
-
-// Parses one step into `step`, or returns why it is invalid. Sleep only advances `atMs`.
-const char* parseStep(JsonArrayConst item, const Timeline::Names& names, uint32_t& atMs, std::optional<Timeline::Step>& step) {
-  using Kind = Timeline::Kind;
-
-  const char* command = item[0].as<const char*>();
-
-  if (command == nullptr) {
-    return "expected [command, ...]";
-  }
-
-  if (strcmp(command, "sleep") == 0) {
-    if (!isMs(item[1])) {
-      return "sleep needs 0..600000 ms";
-    }
-    atMs += item[1].as<uint32_t>();
-    return nullptr;
-  }
-
-  if (strcmp(command, "blink") == 0) {
-    step = Timeline::Step{atMs, Kind::Blink, 0, 0.0f, 0.0f, 0};
-    return nullptr;
-  }
-
-  const struct {
-    const char* command;
-    Kind kind;
-    Timeline::NameResolver resolve;
-  } named[] = {
-    {"preset", Kind::Preset, names.preset},
-    {"eyes", Kind::Eyes, names.eyes},
-    {"face", Kind::Face, names.face},
-  };
-
-  for (const auto& entry : named) {
-    if (strcmp(command, entry.command) != 0) {
-      continue;
-    }
-
-    const char* name = item[1].as<const char*>();
-    uint8_t id = 0;
-
-    if (name == nullptr) {
-      return "needs a name";
-    }
-    if (const char* reason = entry.resolve(name, id)) {
-      return reason;
-    }
-    step = Timeline::Step{atMs, entry.kind, id, 0.0f, 0.0f, 0};
-    return nullptr;
-  }
-
-  if (strcmp(command, "move") == 0) {
-    const char* servo = item[1].as<const char*>();
-    uint8_t index = 0;
-
-    if (servo == nullptr || !findServo(servo, index)) {
-      return "unknown servo";
-    }
-    if (!item[2].is<float>() || !isOptionalMs(item[3])) {
-      return "move needs a position -1..1 and optional duration ms";
-    }
-    step = Timeline::Step{atMs, Kind::Move, index, servoSaturateNorm(item[2].as<float>()), 0.0f, item[3].as<uint32_t>()};
-    return nullptr;
-  }
-
-  if (strcmp(command, "look") == 0) {
-    if (!item[1].is<float>() || !item[2].is<float>() || !isOptionalMs(item[3])) {
-      return "look needs x and y -1..1 and optional duration ms";
-    }
-    step = Timeline::Step{
-      atMs,
-      Kind::Look,
-      0,
-      servoSaturateNorm(item[1].as<float>()),
-      servoSaturateNorm(item[2].as<float>()),
-      item[3].as<uint32_t>()
-    };
-    return nullptr;
-  }
-
-  if (strcmp(command, "open") == 0) {
-    if (!item[1].is<float>() || !isOptionalMs(item[2])) {
-      return "open needs an amount 0..1 and optional duration ms";
-    }
-    step = Timeline::Step{atMs, Kind::Open, 0, std::clamp(item[1].as<float>(), 0.0f, 1.0f), 0.0f, item[2].as<uint32_t>()};
-    return nullptr;
-  }
-
-  return "unknown command";
-}
-
-}  // namespace
-
-std::optional<Timeline> Timeline::parse(
-  const char* json,
-  size_t length,
-  const Names& names,
-  char* error,
-  size_t errorSize
-) {
-  JsonDocument doc;
-
-  if (deserializeJson(doc, json, length) != DeserializationError::Ok || !doc.is<JsonArrayConst>()) {
-    snprintf(error, errorSize, "X-Anim is not a JSON array");
-    return std::nullopt;
-  }
-
-  JsonArrayConst items = doc.as<JsonArrayConst>();
-
-  if (items.size() > kMaxSteps) {
-    snprintf(error, errorSize, "X-Anim has more than %u steps", static_cast<unsigned>(kMaxSteps));
-    return std::nullopt;
-  }
-
-  Timeline timeline;
-  timeline.steps_.reserve(items.size());
-  uint32_t atMs = 0;
-  unsigned index = 0;
-
-  for (JsonArrayConst item : items) {
-    std::optional<Step> step;
-
-    if (const char* reason = parseStep(item, names, atMs, step)) {
-      snprintf(error, errorSize, "step %u: %s", index, reason);
-      return std::nullopt;
-    }
-    if (step) {
-      timeline.steps_.push_back(*step);
-    }
-    index++;
-  }
-
-  return timeline;
-}
-
-const std::vector<Timeline::Step>& Timeline::steps() const {
-  return steps_;
-}
diff --git a/src/animation/timeline.h b/src/animation/timeline.h
deleted file mode 100644
index 6b32286f..00000000
--- a/src/animation/timeline.h
+++ /dev/null
@@ -1,61 +0,0 @@
-#pragma once
-
-#include <cstddef>
-#include <cstdint>
-#include <optional>
-#include <vector>
-
-// A choreography sent alongside streamed audio: a JSON array of steps such as
-// ["sleep", 500], ["preset", "typing"], ["move", "head", 0.6, 300], ["look", -1, 0, 150].
-// Sleeps are folded into each step's start time, measured in playback milliseconds.
-// Steps do not block: steps without a sleep between them start together.
-class Timeline {
-public:
-  enum class Kind : uint8_t {
-    Preset,
-    Move,
-    Eyes,
-    Look,
-    Open,
-    Blink,
-    Face
-  };
-
-  struct Step {
-    uint32_t atMs;
-    Kind kind;
-    // Preset, eye-mode or face id from a resolver, or a servo index for Move.
-    uint8_t target;
-    // Move position, look x or open amount.
-    float x;
-    // Look y.
-    float y;
-    // Time a Move, Look or Open takes to arrive; 0 is as fast as possible.
-    uint32_t durationMs;
-  };
-
-  // Returns nullptr and sets `id` when `name` is usable, else the reason it is not.
-  using NameResolver = const char* (*)(const char* name, uint8_t& id);
-
-  struct Names {
-    NameResolver preset;
-    NameResolver eyes;
-    NameResolver face;
-  };
-
-  static constexpr size_t kMaxSteps = 256;
-  static constexpr uint32_t kMaxSleepMs = 600000;
-
-  static std::optional<Timeline> parse(
-    const char* json,
-    size_t length,
-    const Names& names,
-    char* error,
-    size_t errorSize
-  );
-
-  const std::vector<Step>& steps() const;
-
-private:
-  std::vector<Step> steps_;
-};
diff --git a/src/animation/timeline_player.cpp b/src/animation/timeline_player.cpp
deleted file mode 100644
index bdc0a643..00000000
--- a/src/animation/timeline_player.cpp
+++ /dev/null
@@ -1,130 +0,0 @@
-#include "animation/timeline_player.h"
-
-#include <Arduino.h>
-
-#include <cmath>
-#include <cstring>
-
-#include <TinyEngineerExpressions.h>
-
-#include "animation/registry.h"
-#include "display/eyes.h"
-#include "hardware/servo_wrapper.h"
-
-namespace {
-
-const char* resolvePreset(const char* name, uint8_t& id) {
-  AnimationId anim;
-
-  if (!parseAnimationName(name, anim)) {
-    return "unknown preset";
-  }
-
-  switch (anim) {
-    case AnimationId::None:
-    case AnimationId::Typing:
-    case AnimationId::Reading:
-    case AnimationId::Thinking:
-    case AnimationId::Wakeup:
-      id = static_cast<uint8_t>(anim);
-      return nullptr;
-    default:
-      return "preset not available during playback";
-  }
-}
-
-const char* resolveEyes(const char* name, uint8_t& id) {
-  AnimationId anim;
-
-  if (strcmp(name, "idle") == 0) {
-    anim = AnimationId::None;
-  } else if (!parseAnimationName(name, anim)) {
-    return "unknown eye mode";
-  }
-
-  id = static_cast<uint8_t>(modeByAnimId(anim)->eyeMode);
-  return nullptr;
-}
-
-const char* resolveFace(const char* name, uint8_t& id) {
-  tiny_engineer::expressions::Expression face;
-
-  if (!tiny_engineer::expressions::fromName(name, face)) {
-    return "unknown face";
-  }
-
-  id = static_cast<uint8_t>(face);
-  return nullptr;
-}
-
-const Timeline::Names kNames = {resolvePreset, resolveEyes, resolveFace};
-
-}  // namespace
-
-const Timeline::Names& TimelinePlayer::names() {
-  return kNames;
-}
-
-TimelinePlayer::TimelinePlayer(Timeline timeline)
-  : timeline_(std::move(timeline)), previous_(getAnimation()) {}
-
-void TimelinePlayer::advance(uint32_t playedMs) {
-  const auto& steps = timeline_.steps();
-
-  while (next_ < steps.size() && steps[next_].atMs <= playedMs) {
-    run(steps[next_++]);
-  }
-}
-
-void TimelinePlayer::finish() {
-  setAnimationImmediately(animationIsContinuous(previous_) ? previous_ : AnimationId::None);
-}
-
-void TimelinePlayer::run(const Timeline::Step& step) {
-  switch (step.kind) {
-    case Timeline::Kind::Preset:
-      setAnimationImmediately(static_cast<AnimationId>(step.target));
-      break;
-
-    case Timeline::Kind::Eyes:
-      setEyeMode(static_cast<EyeMode>(step.target), millis());
-      break;
-
-    case Timeline::Kind::Look:
-      eyesLookAt(step.x, step.y, step.durationMs, millis());
-      break;
-
-    case Timeline::Kind::Open:
-      eyesSetOpen(step.x, step.durationMs, millis());
-      break;
-
-    case Timeline::Kind::Blink:
-      eyesBlink(millis());
-      break;
-
-    case Timeline::Kind::Face:
-      eyesShowFace(step.target, millis());
-      break;
-
-    case Timeline::Kind::Move: {
-      if (getAnimation() != AnimationId::Scripted) {
-        // Hand the joints to the script but keep whatever the eyes are doing.
-        const EyeMode eyes = eyeMode();
-        setAnimationImmediately(AnimationId::Scripted);
-        setEyeMode(eyes, millis());
-      }
-      ensureAllServoOutputs();
-
-      ServoWrapper& servo = servoAt(step.target);
-      float speed = SERVO_MAX_SPEED_DEG_S;
-
-      if (step.durationMs > 0) {
-        const float distance = fabsf(servoNormToDeg(step.target, step.x) - servo.angle());
-        speed = fminf(SERVO_MAX_SPEED_DEG_S, fmaxf(1.0f, distance * 1000.0f / step.durationMs));
-      }
-
-      servo.setNormTarget(step.x, speed);
-      break;
-    }
-  }
-}
diff --git a/src/animation/timeline_player.h b/src/animation/timeline_player.h
deleted file mode 100644
index 7a46a62c..00000000
--- a/src/animation/timeline_player.h
+++ /dev/null
@@ -1,25 +0,0 @@
-#pragma once
-
-#include <cstdint>
-
-#include "animation.h"
-#include "animation/timeline.h"
-
-// Runs a Timeline against the audio playback clock, then hands the robot back
-// to the animation that was running.
-class TimelinePlayer {
-public:
-  static const Timeline::Names& names();
-
-  explicit TimelinePlayer(Timeline timeline);
-
-  void advance(uint32_t playedMs);
-  void finish();
-
-private:
-  Timeline timeline_;
-  size_t next_ = 0;
-  AnimationId previous_;
-
-  void run(const Timeline::Step& step);
-};
diff --git a/src/display/eyes.h b/src/display/eyes.h
index cb0e4c2c..b2cd0541 100644
--- a/src/display/eyes.h
+++ b/src/display/eyes.h
@@ -21,7 +21,7 @@ enum class EyeMode {
   Abort,
   Wakeup,
   Dead,
-  Scripted
+  Talking
 };
 
 enum class SleepEyeResult {
@@ -41,15 +41,7 @@ void requestSleepEyeOpen(uint32_t now);
 void clearSleepEyeAnim();
 SleepEyeResult updateSleepEyes(uint32_t now);
 
-// Also clears a scripted face.
 void setEyeMode(EyeMode mode, uint32_t now);
-EyeMode eyeMode();
-
-// POST /play timeline steps. look and open switch to EyeMode::Scripted; x/y are -1..1, amount 0..1.
-void eyesLookAt(float x, float y, uint32_t durationMs, uint32_t now);
-void eyesSetOpen(float amount, uint32_t durationMs, uint32_t now);
-void eyesBlink(uint32_t now);
-void eyesShowFace(uint8_t expression, uint32_t now);
 void triggerEyeImpact(uint32_t now);
 
 const Eye& leftEye();
diff --git a/src/display/eyes/controller.cpp b/src/display/eyes/controller.cpp
index ce1feae8..09eb3882 100644
--- a/src/display/eyes/controller.cpp
+++ b/src/display/eyes/controller.cpp
@@ -14,7 +14,6 @@
 #include "display/eyes/core/impact.h"
 #include "display/eyes/core/internal.h"
 #include "display/eyes/core/util.h"
-#include "display/eyes/modes/scripted.h"
 #include "display/eyes/styles/eye_style.h"
 #include "display/eyes/styles/kaomoji.h"
 #include "settings/settings.h"
@@ -67,10 +66,6 @@ void updateModePose(uint32_t now) {
 }
 
 void drawCurrentEyes(uint32_t now) {
-  if (eyes::drawScriptFace(now)) {
-    return;
-  }
-
   const EyeStyleRenderer* style = currentEyeStyle();
   style->draw(
     g_eyeMode,
@@ -146,6 +141,10 @@ void setModeStartedMs(uint32_t ms) {
   g_modeStartedMs = ms;
 }
 
+EyeMode currentEyeMode() {
+  return g_eyeMode;
+}
+
 void setCurrentEyeMode(EyeMode mode) {
   g_eyeMode = mode;
 }
@@ -180,12 +179,7 @@ void setEyesRunning(bool active) {
 
 }  // namespace eyes
 
-EyeMode eyeMode() {
-  return g_eyeMode;
-}
-
 void setEyeMode(EyeMode mode, uint32_t now) {
-  eyes::clearScriptFace();
   g_eyeMode = mode;
   g_modeStartedMs = now;
   resetImpactState();
diff --git a/src/display/eyes/core/blink.cpp b/src/display/eyes/core/blink.cpp
index a3d4145d..b69c73b3 100644
--- a/src/display/eyes/core/blink.cpp
+++ b/src/display/eyes/core/blink.cpp
@@ -23,7 +23,7 @@ uint8_t g_blinksInSequence = 1;
 uint8_t g_blinksDone = 0;
 
 void scheduleNextBlink(uint32_t now) {
-  switch (eyeMode()) {
+  switch (eyes::currentEyeMode()) {
     case EyeMode::Typing:
       g_nextBlinkMs = now + anim::randRangeMs(1800, 4000);
       break;
diff --git a/src/display/eyes/core/internal.h b/src/display/eyes/core/internal.h
index 63e93918..3efe2746 100644
--- a/src/display/eyes/core/internal.h
+++ b/src/display/eyes/core/internal.h
@@ -9,6 +9,7 @@ namespace eyes {
 uint32_t modeStartedMs();
 void setModeStartedMs(uint32_t ms);
 
+EyeMode currentEyeMode();
 void setCurrentEyeMode(EyeMode mode);
 
 bool forceRedraw();
diff --git a/src/display/eyes/modes/scripted.cpp b/src/display/eyes/modes/scripted.cpp
deleted file mode 100644
index 618233c8..00000000
--- a/src/display/eyes/modes/scripted.cpp
+++ /dev/null
@@ -1,105 +0,0 @@
-#include "display/eyes/modes/scripted.h"
-
-#include "animation/util.h"
-#include "display/eyes.h"
-#include "display/eyes/core/blink.h"
-#include "display/eyes/core/constants.h"
-#include "display/eyes/core/internal.h"
-#include "display/eyes/core/util.h"
-#include "display/eyes/styles/kaomoji.h"
-
-namespace {
-
-namespace expressions = tiny_engineer::expressions;
-
-// Gaze offset at -1 or +1, in pixels; keeps both eyes on the 128x32 panel.
-constexpr float kLookRangeX = 16.0f;
-constexpr float kLookRangeY = 8.0f;
-
-// Set by startScriptedEyes() whenever EyeMode::Scripted begins.
-anim::EasedMove g_lookX = {};
-anim::EasedMove g_lookY = {};
-anim::EasedMove g_open = {};
-
-bool g_faceShowing = false;
-expressions::Expression g_face = expressions::Expression::Idle;
-uint32_t g_faceStartedMs = 0;
-uint32_t g_faceFrameDrawn = UINT32_MAX;
-
-void retarget(anim::EasedMove& move, float target, uint32_t durationMs, uint32_t now) {
-  anim::beginEasedMove(move, anim::easedMoveValue(move, now), target, now, durationMs);
-}
-
-Eye scriptedEye(const Eye& base, uint32_t now) {
-  Eye eye = eyes::renderEye(base, anim::easedMoveValue(g_open, now));
-  eye.x += static_cast<int16_t>(anim::easedMoveValue(g_lookX, now) * kLookRangeX);
-  eye.y += static_cast<int16_t>(anim::easedMoveValue(g_lookY, now) * kLookRangeY);
-  return eye;
-}
-
-void enterScriptedEyes(uint32_t now) {
-  if (eyeMode() != EyeMode::Scripted) {
-    setEyeMode(EyeMode::Scripted, now);
-  }
-}
-
-}  // namespace
-
-void startScriptedEyes(uint32_t /*now*/) {
-  g_lookX = {};
-  g_lookY = {};
-  g_open = {1.0f, 1.0f, 0, 0, false};
-}
-
-void updateScriptedEyes(uint32_t now) {
-  mutableLeftEye() = scriptedEye(eyes::DEFAULT_LEFT, now);
-  mutableRightEye() = scriptedEye(eyes::DEFAULT_RIGHT, now);
-}
-
-void eyesLookAt(float x, float y, uint32_t durationMs, uint32_t now) {
-  enterScriptedEyes(now);
-  retarget(g_lookX, x, durationMs, now);
-  retarget(g_lookY, y, durationMs, now);
-}
-
-void eyesSetOpen(float amount, uint32_t durationMs, uint32_t now) {
-  enterScriptedEyes(now);
-  retarget(g_open, amount, durationMs, now);
-}
-
-void eyesBlink(uint32_t now) {
-  blinkScheduleSoon(now, 0, 0);
-}
-
-void eyesShowFace(uint8_t expression, uint32_t now) {
-  g_face = static_cast<expressions::Expression>(expression);
-  g_faceStartedMs = now;
-  g_faceFrameDrawn = UINT32_MAX;
-  g_faceShowing = true;
-  eyes::requestForceRedraw();
-}
-
-namespace eyes {
-
-bool drawScriptFace(uint32_t now) {
-  if (!g_faceShowing) {
-    return false;
-  }
-
-  // Faces change frame every kFrameDurationMs; skip the I2C flush in between.
-  const uint32_t elapsed = now - g_faceStartedMs;
-  const uint32_t frame = elapsed / expressions::kFrameDurationMs;
-
-  if (frame != g_faceFrameDrawn || forceRedraw()) {
-    drawKaomojiFrame(g_face, elapsed);
-    g_faceFrameDrawn = frame;
-  }
-
-  return true;
-}
-
-void clearScriptFace() {
-  g_faceShowing = false;
-}
-
-}  // namespace eyes
diff --git a/src/display/eyes/modes/scripted.h b/src/display/eyes/modes/scripted.h
deleted file mode 100644
index 6cca11d6..00000000
--- a/src/display/eyes/modes/scripted.h
+++ /dev/null
@@ -1,15 +0,0 @@
-#pragma once
-
-#include <stdint.h>
-
-// EyeMode::Scripted: gaze and lids driven by POST /play look/open steps.
-void startScriptedEyes(uint32_t now);
-void updateScriptedEyes(uint32_t now);
-
-namespace eyes {
-
-// A scripted face replaces the eyes in every style until the next setEyeMode().
-bool drawScriptFace(uint32_t now);
-void clearScriptFace();
-
-}  // namespace eyes
diff --git a/src/display/eyes/modes/talking.cpp b/src/display/eyes/modes/talking.cpp
new file mode 100644
index 00000000..3148a326
--- /dev/null
+++ b/src/display/eyes/modes/talking.cpp
@@ -0,0 +1,38 @@
+#include "display/eyes/modes/talking.h"
+
+#include "animation/util.h"
+#include "display/eyes.h"
+#include "display/eyes/core/constants.h"
+#include "display/eyes/core/util.h"
+
+namespace {
+
+int16_t g_glanceX = 0;
+int16_t g_glanceY = 0;
+uint32_t g_nextGlanceMs = 0;
+
+}  // namespace
+
+void startTalkingEyes(uint32_t now) {
+  g_glanceX = 0;
+  g_glanceY = 0;
+  g_nextGlanceMs = now + anim::randRangeMs(400, 900);
+}
+
+void updateTalkingEyes(uint32_t now) {
+  // Mostly on the listener, with short glances away the way people look while speaking.
+  if (now >= g_nextGlanceMs) {
+    const bool away = g_glanceX == 0 && anim::randChance(45);
+    g_glanceX = away ? (int16_t)(anim::randChance(50) ? 4 : -4) : 0;
+    g_glanceY = away ? (int16_t)anim::randRangeMs(0, 2) - 2 : 0;
+    g_nextGlanceMs = now + (away ? anim::randRangeMs(250, 600) : anim::randRangeMs(700, 1600));
+  }
+
+  Eye& left = mutableLeftEye();
+  Eye& right = mutableRightEye();
+
+  left = eyes::eyeWithHeight((int16_t)(eyes::DEFAULT_LEFT.x + g_glanceX), eyes::DEFAULT_LEFT.width, 15);
+  right = eyes::eyeWithHeight((int16_t)(eyes::DEFAULT_RIGHT.x + g_glanceX), eyes::DEFAULT_RIGHT.width, 15);
+  left.y += g_glanceY;
+  right.y += g_glanceY;
+}
diff --git a/src/display/eyes/modes/talking.h b/src/display/eyes/modes/talking.h
new file mode 100644
index 00000000..ddafa478
--- /dev/null
+++ b/src/display/eyes/modes/talking.h
@@ -0,0 +1,6 @@
+#pragma once
+
+#include <stdint.h>
+
+void startTalkingEyes(uint32_t now);
+void updateTalkingEyes(uint32_t now);
diff --git a/src/display/eyes/styles/kaomoji.cpp b/src/display/eyes/styles/kaomoji.cpp
index e31094e9..217507bb 100644
--- a/src/display/eyes/styles/kaomoji.cpp
+++ b/src/display/eyes/styles/kaomoji.cpp
@@ -32,7 +32,6 @@ expressions::Expression expressionFor(
 
   switch (mode) {
     case EyeMode::Idle:
-    case EyeMode::Scripted:
       return expressions::Expression::Idle;
     case EyeMode::Typing:
     case EyeMode::Thinking:
@@ -43,6 +42,7 @@ expressions::Expression expressionFor(
     case EyeMode::Ring:
       return expressions::Expression::Surprise;
     case EyeMode::Welcome:
+    case EyeMode::Talking:
       return expressions::Expression::Happy;
     case EyeMode::Error:
       return expressions::Expression::Angry;
@@ -75,14 +75,14 @@ void drawKaomoji(
     g_expressionArmed = true;
   }
 
-  drawKaomojiFrame(expression, now - g_expressionStartedMs);
-}
-
-}  // namespace
+  const uint32_t elapsed = now - g_expressionStartedMs;
 
-void drawKaomojiFrame(tiny_engineer::expressions::Expression expression, uint32_t elapsedMs) {
-  if (!oledAvailable ||
-      !expressions::render(expression, elapsedMs, g_kaomojiFrame, sizeof(g_kaomojiFrame))) {
+  if (!expressions::render(
+        expression,
+        elapsed,
+        g_kaomojiFrame,
+        sizeof(g_kaomojiFrame)
+      )) {
     return;
   }
 
@@ -98,6 +98,8 @@ void drawKaomojiFrame(tiny_engineer::expressions::Expression expression, uint32_
   display.display();
 }
 
+}  // namespace
+
 void kaomojiResetPlayback(uint32_t now) {
   g_expressionArmed = false;
   g_expressionStartedMs = now;
diff --git a/src/display/eyes/styles/kaomoji.h b/src/display/eyes/styles/kaomoji.h
index 47a61d8a..51046ecb 100644
--- a/src/display/eyes/styles/kaomoji.h
+++ b/src/display/eyes/styles/kaomoji.h
@@ -2,9 +2,5 @@
 
 #include <cstdint>
 
-#include <TinyEngineerExpressions.h>
-
 // Reset kaomoji face playback so the next draw starts at frame 0.
 void kaomojiResetPlayback(uint32_t now);
-
-void drawKaomojiFrame(tiny_engineer::expressions::Expression expression, uint32_t elapsedMs);
diff --git a/src/hardware/rgb.cpp b/src/hardware/rgb.cpp
index f01e42e1..96ffd6d4 100644
--- a/src/hardware/rgb.cpp
+++ b/src/hardware/rgb.cpp
@@ -109,10 +109,10 @@ void resolveAnimationTarget(AnimationId id, uint8_t& r, uint8_t& g, uint8_t& b)
     case AnimationId::Typing:
     case AnimationId::Reading:
     case AnimationId::Thinking:
+    case AnimationId::Talking:
     case AnimationId::Welcome:
     case AnimationId::Ring:
     case AnimationId::Wakeup:
-    case AnimationId::Scripted:
       r = RGB_ANIM_WHITE;
       g = RGB_ANIM_WHITE;
       b = RGB_ANIM_WHITE;
diff --git a/src/http/http_server.cpp b/src/http/http_server.cpp
index 1fad3a59..8abbde43 100644
--- a/src/http/http_server.cpp
+++ b/src/http/http_server.cpp
@@ -17,8 +17,8 @@ void startHttpServer() {
 
   refreshMdnsHostname();
 
-  static const char* kCollectHeaders[] = {"Authorization", "X-Anim"};
-  server.collectHeaders(kCollectHeaders, sizeof(kCollectHeaders) / sizeof(kCollectHeaders[0]));
+  static const char* kCollectHeaders[] = {"Authorization"};
+  server.collectHeaders(kCollectHeaders, 1);
 
   registerHttpRoutes();
   server.begin();
diff --git a/test/test_expressions/test_expressions.cpp b/test/test_expressions/test_expressions.cpp
index 37910bb5..4aa4096e 100644
--- a/test/test_expressions/test_expressions.cpp
+++ b/test/test_expressions/test_expressions.cpp
@@ -90,24 +90,9 @@ void test_callers_can_render_independently() {
   TEST_ASSERT_EQUAL_UINT8_ARRAY(first, again, sizeof first);
 }
 
-void test_from_name_round_trips_every_name() {
-  for (std::size_t i = 0; i < expr::kExpressionCount; i++) {
-    const auto expected = static_cast<expr::Expression>(i);
-    auto parsed = expr::Expression::Idle;
-    TEST_ASSERT_TRUE(expr::fromName(expr::name(expected), parsed));
-    TEST_ASSERT_EQUAL_UINT8(i, static_cast<uint8_t>(parsed));
-  }
-
-  auto untouched = expr::Expression::Love;
-  TEST_ASSERT_FALSE(expr::fromName("grumpy", untouched));
-  TEST_ASSERT_FALSE(expr::fromName(nullptr, untouched));
-  TEST_ASSERT_TRUE(untouched == expr::Expression::Love);
-}
-
 int main() {
   UNITY_BEGIN();
   RUN_TEST(test_names_and_invalid_ids);
-  RUN_TEST(test_from_name_round_trips_every_name);
   RUN_TEST(test_all_frames_match_original_designs);
   RUN_TEST(test_invalid_inputs_leave_buffer_untouched);
   RUN_TEST(test_frame_timing_and_loop_boundaries);
diff --git a/test/test_timeline/test_timeline.cpp b/test/test_timeline/test_timeline.cpp
deleted file mode 100644
index 4fc6aab4..00000000
--- a/test/test_timeline/test_timeline.cpp
+++ /dev/null
@@ -1,131 +0,0 @@
-#include <unity.h>
-
-#include <cstring>
-#include <string>
-
-#include "animation/timeline.h"
-
-namespace {
-
-const char* resolvePreset(const char* name, uint8_t& id) {
-  if (strcmp(name, "typing") == 0) {
-    id = 7;
-    return nullptr;
-  }
-  return strcmp(name, "ring") == 0 ? "preset plays its own audio" : "unknown preset";
-}
-
-const char* resolveEyes(const char* name, uint8_t& id) {
-  id = 3;
-  return strcmp(name, "thinking") == 0 ? nullptr : "unknown";
-}
-
-const char* resolveFace(const char* name, uint8_t& id) {
-  id = 9;
-  return strcmp(name, "love") == 0 ? nullptr : "unknown face";
-}
-
-const Timeline::Names kNames = {resolvePreset, resolveEyes, resolveFace};
-
-char g_error[96];
-
-std::optional<Timeline> parse(const std::string& json) {
-  g_error[0] = '\0';
-  return Timeline::parse(json.data(), json.size(), kNames, g_error, sizeof(g_error));
-}
-
-}  // namespace
-
-void test_sleeps_set_start_times_and_moves_share_them() {
-  const auto timeline = parse(
-    R"([["preset","typing"],["sleep",500],["move","head",0.5,300],["move","neck",-0.5],["sleep",250],["eyes","thinking"]])"
-  );
-
-  TEST_ASSERT_TRUE(timeline.has_value());
-  const auto& steps = timeline->steps();
-  TEST_ASSERT_EQUAL_size_t(4, steps.size());
-  TEST_ASSERT_EQUAL_UINT32(0, steps[0].atMs);
-  TEST_ASSERT_EQUAL_UINT8(7, steps[0].target);
-  TEST_ASSERT_EQUAL_UINT32(500, steps[1].atMs);
-  TEST_ASSERT_EQUAL_UINT32(500, steps[2].atMs);
-  TEST_ASSERT_EQUAL_UINT32(750, steps[3].atMs);
-  TEST_ASSERT_TRUE(steps[3].kind == Timeline::Kind::Eyes);
-}
-
-void test_move_resolves_servo_and_clamps_position() {
-  const auto timeline = parse(R"([["move","HAND_RIGHT",3,200],["move","body",-0.25]])");
-
-  TEST_ASSERT_TRUE(timeline.has_value());
-  const auto& steps = timeline->steps();
-  TEST_ASSERT_EQUAL_UINT8(3, steps[0].target);
-  TEST_ASSERT_EQUAL_FLOAT(1.0f, steps[0].x);
-  TEST_ASSERT_EQUAL_UINT32(200, steps[0].durationMs);
-  TEST_ASSERT_EQUAL_UINT8(4, steps[1].target);
-  TEST_ASSERT_EQUAL_UINT32(0, steps[1].durationMs);
-}
-
-void test_eye_steps() {
-  const auto timeline = parse(R"([["look",-2,0.5,150],["open",0.3],["sleep",100],["blink"],["face","love"]])");
-
-  TEST_ASSERT_TRUE(timeline.has_value());
-  const auto& steps = timeline->steps();
-  TEST_ASSERT_EQUAL_size_t(4, steps.size());
-  TEST_ASSERT_TRUE(steps[0].kind == Timeline::Kind::Look);
-  TEST_ASSERT_EQUAL_FLOAT(-1.0f, steps[0].x);
-  TEST_ASSERT_EQUAL_FLOAT(0.5f, steps[0].y);
-  TEST_ASSERT_EQUAL_UINT32(150, steps[0].durationMs);
-  TEST_ASSERT_TRUE(steps[1].kind == Timeline::Kind::Open);
-  TEST_ASSERT_EQUAL_FLOAT(0.3f, steps[1].x);
-  TEST_ASSERT_EQUAL_UINT32(0, steps[1].durationMs);
-  TEST_ASSERT_TRUE(steps[2].kind == Timeline::Kind::Blink);
-  TEST_ASSERT_EQUAL_UINT32(100, steps[2].atMs);
-  TEST_ASSERT_TRUE(steps[3].kind == Timeline::Kind::Face);
-  TEST_ASSERT_EQUAL_UINT8(9, steps[3].target);
-
-  TEST_ASSERT_FALSE(parse(R"([["look",0.5]])").has_value());
-  TEST_ASSERT_FALSE(parse(R"([["open","wide"]])").has_value());
-  TEST_ASSERT_FALSE(parse(R"([["face","grumpy"]])").has_value());
-  TEST_ASSERT_EQUAL_STRING("step 0: unknown face", g_error);
-}
-
-void test_resolver_reason_is_reported_with_step_index() {
-  TEST_ASSERT_FALSE(parse(R"([["sleep",10],["preset","ring"]])").has_value());
-  TEST_ASSERT_EQUAL_STRING("step 1: preset plays its own audio", g_error);
-}
-
-void test_rejects_malformed_steps() {
-  TEST_ASSERT_FALSE(parse(R"({"preset":"typing"})").has_value());
-  TEST_ASSERT_EQUAL_STRING("X-Anim is not a JSON array", g_error);
-
-  TEST_ASSERT_FALSE(parse(R"([["wiggle"]])").has_value());
-  TEST_ASSERT_EQUAL_STRING("step 0: unknown command", g_error);
-
-  TEST_ASSERT_FALSE(parse(R"([["move","tail",0.1]])").has_value());
-  TEST_ASSERT_EQUAL_STRING("step 0: unknown servo", g_error);
-
-  TEST_ASSERT_FALSE(parse(R"([["move","head"]])").has_value());
-  TEST_ASSERT_FALSE(parse(R"([["move","head",0.2,-5]])").has_value());
-  TEST_ASSERT_FALSE(parse(R"([["sleep",-1]])").has_value());
-  TEST_ASSERT_FALSE(parse(R"([["sleep",600001]])").has_value());
-}
-
-void test_rejects_too_many_steps() {
-  std::string json = "[";
-  for (size_t i = 0; i <= Timeline::kMaxSteps; i++) {
-    json += i == 0 ? "[\"sleep\",1]" : ",[\"sleep\",1]";
-  }
-  json += "]";
-
-  TEST_ASSERT_FALSE(parse(json).has_value());
-}
-
-int main(int, char**) {
-  UNITY_BEGIN();
-  RUN_TEST(test_sleeps_set_start_times_and_moves_share_them);
-  RUN_TEST(test_move_resolves_servo_and_clamps_position);
-  RUN_TEST(test_eye_steps);
-  RUN_TEST(test_resolver_reason_is_reported_with_step_index);
-  RUN_TEST(test_rejects_malformed_steps);
-  RUN_TEST(test_rejects_too_many_steps);
-  return UNITY_END();
-}

From e7d3309f774624d428babc02baf5320603cd669a Mon Sep 17 00:00:00 2001
From: shodan <mega@ioexception.at>
Date: Sun, 4 Oct 2026 19:22:00 +0200
Subject: [PATCH 17/21] refactor(http): run one named animation during POST
 /play

/play now plays the clip while `talking` runs, and /play/{name} picks
talking, typing, reading, thinking or none instead. The animation starts
with the first audio sample and the previous continuous animation comes
back when the clip ends.

The X-Anim timeline, the scripted animation and eye mode, the 8 KB
header limit, ArduinoJson and the Kokoro / chordsheet skill move to a
follow-up; the Claude Code play command takes --name instead of --anim.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VYDrnWNM6nbcQ1nx8aua93
---
 README.md                                     |  2 +-
 docs/api.md                                   | 46 ++++--------
 docs/hardware/testing.md                      |  2 +-
 docs/integration.md                           | 41 ++--------
 packages/tiny-engineer-claude-code/src/cli.js | 21 ++----
 .../tiny-engineer-claude-code/src/play.js     | 51 ++++---------
 .../test/play.test.js                         | 29 +++-----
 platformio.ini                                |  5 --
 src/animation/controller.cpp                  |  4 +
 src/http/index_page.cpp                       | 20 +++--
 src/http/json.cpp                             |  2 +-
 src/http/play_handlers.cpp                    | 74 ++++++++++---------
 src/http/routes.cpp                           |  8 ++
 src/http/settings_handlers.cpp                |  2 +-
 14 files changed, 116 insertions(+), 191 deletions(-)

diff --git a/README.md b/README.md
index 18e1bab1..ef1638a0 100644
--- a/README.md
+++ b/README.md
@@ -14,7 +14,7 @@
 **Works with**
 
 - **Ready integrations:** [Claude Code](docs/integration.md#4-claude-code-dedicated-script) · [Cursor](docs/hooks.md) · [Antigravity](docs/integration.md#3-antigravity-cli-dedicated-script)
-- **Any agent with HTTP:** Codex, Windsurf, custom scripts, `POST /anim` on your LAN ([integration guide](docs/integration.md)), or `POST /play` to stream speech with custom moves, gaze and faces ([HTTP API](docs/api.md#post-play))
+- **Any agent with HTTP:** Codex, Windsurf, custom scripts, `POST /anim` on your LAN ([integration guide](docs/integration.md)), or `POST /play` to stream speech while the robot talks along ([HTTP API](docs/api.md#post-play))
 
 ## What it feels like
 
diff --git a/docs/api.md b/docs/api.md
index 970f4a21..60788d9b 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -455,7 +455,7 @@ curl http://tiny-engineer.local/anim
 
 | Field | Meaning |
 | --- | --- |
-| `animation` | `none`, `typing`, `reading`, `thinking`, `ring`, `welcome`, `attention`, `error`, `abort`, `dead`, `wakeup`, or `sleep`; `scripted` while a [`POST /play`](#post-play) timeline moves the joints (not accepted by `POST /anim`) |
+| `animation` | `none`, `typing`, `reading`, `thinking`, `talking`, `ring`, `welcome`, `attention`, `error`, `abort`, `dead`, `wakeup`, or `sleep` |
 
 ### `POST /anim`
 
@@ -463,12 +463,13 @@ Request an animation switch. Each animation runs at least **1s**; if the current
 
 | Param | Type | Values |
 | --- | --- | --- |
-| `name` | string | `none`, `typing`, `reading`, `thinking`, `ring`, `welcome`, `attention`, `error`, `abort`, `dead`, `wakeup`, `sleep` |
+| `name` | string | `none`, `typing`, `reading`, `thinking`, `talking`, `ring`, `welcome`, `attention`, `error`, `abort`, `dead`, `wakeup`, `sleep` |
 
 ```bash
 curl -X POST "http://tiny-engineer.local/anim?name=typing"
 curl -X POST "http://tiny-engineer.local/anim?name=reading"
 curl -X POST "http://tiny-engineer.local/anim?name=thinking"
+curl -X POST "http://tiny-engineer.local/anim?name=talking"
 curl -X POST "http://tiny-engineer.local/anim?name=ring"
 curl -X POST "http://tiny-engineer.local/anim?name=welcome"
 curl -X POST "http://tiny-engineer.local/anim?name=wakeup"
@@ -494,6 +495,7 @@ Durations and quoted lines below are the stock clips in [`assets/`](../assets/).
 | `typing` | **Continuous.** Alternating hands with randomness (15° band from hand limits). Head nods slowly on lowest 10° of head limits. Body sways ±5° around mid; neck counters opposite so head stays put. Runs until replaced, or until `continuous_timeout` triggers `attention`. Same-name re-`POST` refreshes that timeout without restarting motion. |
 | `reading` | **Continuous.** Hands/body park as in `none`. Head nods on same lowest 10° band as typing, but slower. Neck sweeps ±10° around mid; right (angle down) slower than left (angle up). Occasional right-hand down-arrow bursts (1–3 presses, same 15° band as typing). Runs until replaced, or until `continuous_timeout` triggers `attention`. Same-name re-`POST` refreshes that timeout without restarting motion. |
 | `thinking` | **Continuous.** Hands/body park as in `none`. Head (pitch) and neck (yaw) ease from the current pose into thinking poses (up + slight left/right). Move → pause → optional micro-adjust (sometimes chained) → pause; nearby pose drift with occasional larger shifts after ~2.2 s, more often over time. Axes stagger start/duration; no periodic sway. Runs until replaced, or until `continuous_timeout` triggers `attention`. Same-name re-`POST` refreshes that timeout without restarting motion. |
+| `talking` | **Continuous.** Speaking fidget with no sound of its own, used by [`POST /play`](#post-play) while a clip plays. Hands and body park as in `none` except for an occasional right-hand gesture. The head faces the user just above mid and nods quickly on random beats, then settles; the neck drifts slowly. **Classic eyes:** a little taller than idle, mostly on the user with short glances away. Runs until replaced, or until `continuous_timeout` triggers `attention`. |
 | `ring` | **One-shot** service-bell gesture; does not loop. Wind-up (body `min`, neck mid, head mid+10°, both hands `max`) → fast right-hand strike to `min+5°` with head to `min` → plays `bell.wav` once on strike (LittleFS; same `uploadfs` requirement as `/test/audio/bell`) → slower bounce to `min+20°` → return to `none` pose and stop. After completion, `GET /anim` reports `none`. |
 | `welcome` | **One-shot** hello gesture synced to `welcome.wav` (~2.7 s). Right hand raises during "Hello, human.", holds through the pause, wiggles during "What are we building today?", then lowers. Head nods to mid+10° and returns. Plays automatically after successful Wi-Fi connect at boot; also via API. Requires `welcome.wav` on LittleFS (same `uploadfs` flow as `bell.wav`). After completion, `GET /anim` reports `none`. |
 | `attention` | Friendly input-request gesture synced to `attention.wav` (~3.0 s, "pst... human.... you might want to take a look"). Moves into a calm prompt pose first (centered body/neck, head slightly up, right hand raised partway), waits until all servos stop, then plays audio with light neck/head/hand motion during playback (whisper hold → lean toward user → glance/point on "take a look"). **Classic eyes:** phased blink/look cues during audio. After audio ends (or if audio fails to start), holds a gentle waiting loop for **1 minute** (soft head/neck drifts plus occasional slight right-hand waves), then returns to `none`. Requires `attention.wav` on LittleFS (same `uploadfs` flow as `bell.wav`). |
@@ -513,7 +515,7 @@ When `eyes_style=kaomoji`, the OLED shows looping faces from the expression libr
 | `typing`, `thinking` | Thinking |
 | `reading`, `attention` | Curious |
 | `ring` | Surprise |
-| `welcome` | Happy |
+| `welcome`, `talking` | Happy |
 | `error` | Angry |
 | `abort` | Panic |
 | `wakeup` | Sleepy |
@@ -534,54 +536,36 @@ Wrong params return **400**:
 | `error` | When |
 | --- | --- |
 | `missing name` | Query param `name` absent |
-| `unknown animation` | `name` not `none`, `typing`, `reading`, `thinking`, `ring`, `welcome`, `attention`, `error`, `abort`, `dead`, `wakeup`, or `sleep` |
+| `unknown animation` | `name` not `none`, `typing`, `reading`, `thinking`, `talking`, `ring`, `welcome`, `attention`, `error`, `abort`, `dead`, `wakeup`, or `sleep` |
 
 ### `POST /play`
 
-Streams a WAV to the speaker and optionally drives the robot from a timeline while it plays. The body is played as it arrives, so clips of any length need no storage on the robot. The response comes when the clip ends.
+Streams a WAV to the speaker while one animation runs, then returns to the continuous animation (`typing`, `reading`, `thinking`, `talking`) that was running before the request, otherwise to `none`. The body is played as it arrives, so clips of any length need no storage on the robot. The response comes when the clip ends.
 
 | Part | Value |
 | --- | --- |
+| Path | `/play` runs `talking`; `/play/{name}` runs `talking`, `typing`, `reading`, `thinking`, or `none`. Animations with their own sound are rejected so two clips never overlap |
 | Body | WAV, 16-bit mono PCM at 22050 Hz (the firmware `SAMPLE_RATE`). `Content-Length` is required. Chunks other than `fmt ` and `data` are skipped |
-| `X-Anim` header | Optional JSON array of timeline steps, up to 8 KB and 256 steps |
 | `Authorization` | `Bearer <token>` when `access_token` is set |
 
-Timeline steps run in order. Only `sleep` advances the clock, so steps without a `sleep` between them start together. The clock is the audio playback position: if the network stalls, the timeline waits with the audio.
-
-| Step | Effect |
-| --- | --- |
-| `["sleep", ms]` | Wait `ms` (0–600000) of playback |
-| `["preset", name]` | Run an animation without its sound: `none`, `typing`, `reading`, `thinking`, or `wakeup`. Drives all joints and the eyes |
-| `["move", servo, to, ms?]` | Move `head`, `neck`, `hand_left`, `hand_right`, or `body` to pose position `to` (−1 = saved min, 1 = saved max) so it arrives after `ms`. Without `ms` it moves at the maximum speed (140°/s), which also caps short durations. Stops the running preset and switches to the `scripted` animation; other joints hold where they are and the eyes keep their mode |
-| `["eyes", mode]` | Switch the eye mode: `idle` or any `/anim` name |
-| `["look", x, y, ms?]` | Gaze offset reached after `ms`: `x` −1 screen left to 1 screen right, `y` −1 up to 1 down |
-| `["open", amount, ms?]` | Lid opening, 0 closed to 1 normal, reached after `ms` |
-| `["blink"]` | One blink |
-| `["face", name]` | Animated face from the expression library: `idle`, `happy`, `laugh`, `wink`, `curious`, `thinking`, `surprise`, `smug`, `sleepy`, `sleep`, `sad`, `cry`, `angry`, `panic`, `shy`, or `love` |
-
-`look` and `open` switch the eyes to a scripted mode and reshape them in the current `eyes_style`; `kaomoji` shows its idle face. A `face` replaces the eyes until the next `look`, `open`, `eyes`, or `preset` step. `eyes` and `preset` clear all scripted eye state.
-
-When the clip ends, steps that have not run are dropped. The robot returns to the continuous animation (`typing`, `reading`, `thinking`) that was running before the request, otherwise to `none`.
+The animation starts with the first audio sample, so a rejected request never moves the robot. While the clip plays the robot keeps its eyes, LED and sleep timer running, and the clip counts as activity.
 
 ```bash
-curl -X POST http://tiny-engineer.local/play \
-  -H 'Content-Type: audio/wav' \
-  -H 'X-Anim: [["preset","thinking"],["sleep",800],["move","head",0.6,300],["move","neck",-0.3,300],["face","happy"],["sleep",1200],["look",-1,0,150]]' \
-  --data-binary @clip.wav
+curl -X POST http://tiny-engineer.local/play -H 'Content-Type: audio/wav' --data-binary @clip.wav
+curl -X POST http://tiny-engineer.local/play/thinking -H 'Content-Type: audio/wav' --data-binary @hmm.wav
 ```
 
 ```json
 { "ok": true, "played_ms": 3000 }
 ```
 
-The Claude Code CLI wraps this for agents: `tiny-engineer-claude-code play clip.wav --anim '[...]'` ([integration.md](integration.md#4-claude-code-dedicated-script)). [`scripts/say.py`](../packages/tiny-engineer-claude-code/skills/tiny-engineer-play/scripts/say.py) makes a speech clip in this format and prints when each word starts ([integration.md](integration.md#speech-for-post-play)).
+The Claude Code CLI wraps this for agents: `tiny-engineer-claude-code play clip.wav [--name thinking]` ([integration.md](integration.md#4-claude-code-dedicated-script)).
 
 Errors arrive before any audio plays:
 
 | Status | `error` | When |
 | --- | --- | --- |
-| `400` | `step N: ...` | Timeline step `N` (0-based) is invalid, names an unknown servo, eye mode or face, or a preset that plays its own sound |
-| `400` | `X-Anim is not a JSON array` | Header is not a JSON array |
+| `400` | `name must be talking, typing, reading, thinking or none` | `{name}` is unknown or has its own sound |
 | `415` | `expected 16-bit mono PCM at 22050 Hz` | WAV format or sample rate differs |
 | `415` | `not a WAV file`, `no audio data` | Body is not a RIFF/WAVE file, or has no `data` chunk |
 
@@ -589,7 +573,7 @@ Errors arrive before any audio plays:
 
 | Status | Body | When |
 | --- | --- | --- |
-| `400` | `{"ok":false,"error":"..."}` | Bad `/test/servo`, `/setup/servo`, `/setup/led`, `/setup/audio`, `/setup/oled`, or `/anim` params, or a bad `/play` timeline (see tables above) |
+| `400` | `{"ok":false,"error":"..."}` | Bad `/test/servo`, `/setup/servo`, `/setup/led`, `/setup/audio`, `/setup/oled`, `/anim`, or `/play` params (see tables above) |
 | `401` | `{"ok":false,"error":"unauthorized"}` | Access token configured and `Authorization: Bearer` missing or wrong |
 | `404` | `{"ok":false,"error":"not found"}` | Unknown path |
 | `415` | `{"ok":false,"error":"..."}` | `/play` body is not a supported WAV |
@@ -601,7 +585,7 @@ Test routes are **POST**. GET/prefetch would move hardware. `/anim` allows **GET
 
 Test handlers **block** until the test finishes. The client waits. After each test, OLED returns to `ROBOT READY` plus IP (or `WIFI FAIL`).
 
-`/anim` responses return immediately; typing motion runs in the main loop via non-blocking servo updates. Animation switches may defer up to 1s so the active animation holds its minimum duration; only the latest pending request is applied. Continuous animations (`typing`, `reading`, `thinking`) that stay active longer than `continuous_timeout` minutes switch to `attention`, which holds ~1 minute then finishes to `none`. Re-`POST`ing the same continuous animation (e.g. `typing` while already `typing`) does not restart motion, but resets the continuous-timeout clock.
+`/anim` responses return immediately; typing motion runs in the main loop via non-blocking servo updates. Animation switches may defer up to 1s so the active animation holds its minimum duration; only the latest pending request is applied. Continuous animations (`typing`, `reading`, `thinking`, `talking`) that stay active longer than `continuous_timeout` minutes switch to `attention`, which holds ~1 minute then finishes to `none`. Re-`POST`ing the same continuous animation (e.g. `typing` while already `typing`) does not restart motion, but resets the continuous-timeout clock.
 
 The onboard RGB LED follows the active animation (see [RGB LED](#rgb-led)).
 
diff --git a/docs/hardware/testing.md b/docs/hardware/testing.md
index 9c5e8d6a..7bdf4d08 100644
--- a/docs/hardware/testing.md
+++ b/docs/hardware/testing.md
@@ -109,7 +109,7 @@ curl -X POST "http://tiny-engineer.local/test/servo?index=0&angle=90"
 | `GET` | `/auth` | Auth status (`ok`, `required`, `wifi_configured`, `provisioning`) — always public |
 | `GET` | `/health` | Health JSON — full field list in [api.md](../api.md#get-health) |
 | `GET` / `POST` | `/anim` | Current animation / start one (`name`, optional `interrupt`) — full params in [api.md](../api.md#post-anim) |
-| `POST` | `/play` | Stream a WAV with an optional `X-Anim` timeline; answers when the clip ends — full params in [api.md](../api.md#post-play) |
+| `POST` | `/play` | Stream a WAV while `talking` (or `/play/{name}`) runs; answers when the clip ends — full params in [api.md](../api.md#post-play) |
 | `GET` | `/settings` | Persistent settings (`sleep_timeout`, `hostname`, `volume`, `welcome`, `serial_log`, `continuous_timeout`, `loading`, `eyes_style`, `access_token_set`, `wifi_configured`, `wifi_ssid`, `wifi_password_set`, `servo_mins`, `servo_maxs`, `rgb_order`, `oled_rotate_180`) |
 | `POST` | `/settings?...&wifi_ssid=&wifi_password=` | Update NVS settings; WiFi params setup-AP-only and tested before save; `reboot_required` if hostname changed |
 | `POST` | `/settings?...&servo_mins=&servo_maxs=` | Servo min/max comma lists; setup-AP-only |
diff --git a/docs/integration.md b/docs/integration.md
index 8f8f8e41..d82589d2 100644
--- a/docs/integration.md
+++ b/docs/integration.md
@@ -105,29 +105,6 @@ curl http://tiny-engineer.local/health
 
 More routes (tests, servo, web UI): [`api.md`](api.md).
 
-### Speech for `POST /play`
-
-[`scripts/say.py`](../packages/tiny-engineer-claude-code/skills/tiny-engineer-play/scripts/say.py) speaks a line in the robot's voice: [Kokoro](https://huggingface.co/hexgrad/Kokoro-82M) text-to-speech through a tin-can filter, written as a WAV that [`POST /play`](api.md#post-play) accepts. The script lives in the Claude Code skill and `scripts/say.py` links to it. It needs [uv](https://docs.astral.sh/uv/) and ffmpeg. The first run installs its Python dependencies and downloads the model (about 330 MB).
-
-```bash
-scripts/say.py "Build passed. Ship it!" -o /tmp/te-clip.wav
-```
-
-```json
-{"wav": "/tmp/te-clip.wav", "duration_ms": 2200, "words": [["Build", 375], ["passed", 650], ["Ship", 1188], ["it", 1475]]}
-```
-
-`words` holds the start of each word in milliseconds of the clip, so an agent can put a `move` or `face` step on the word it belongs to. `--voice` picks another [Kokoro voice](https://huggingface.co/hexgrad/Kokoro-82M/blob/main/VOICES.md) (default `am_michael`), `--plain` skips the filter, `--rate` matches a robot built with another sample rate.
-
-`perform.py`, next to it in the skill, takes one string with cues in front of the words they belong to, speaks it, times the cues against the words and sends it:
-
-```bash
-packages/tiny-engineer-claude-code/skills/tiny-engineer-play/scripts/perform.py \
-  "{mood: proud}[nod]Build passed. {pause: 300}[look:-1,0/200]All [look:1,0/200]tests [cheer]green."
-```
-
-The cue syntax is in the skill's [`SKILL.md`](../packages/tiny-engineer-claude-code/skills/tiny-engineer-play/SKILL.md). `--check` validates the string without speaking; `--dry-run` prints the compiled timeline instead of sending it.
-
 ---
 
 ## 2. Cursor dedicated script
@@ -261,24 +238,16 @@ Inside this firmware repository, [`.claude/settings.json`](../.claude/settings.j
 
 To use it in every project, copy the `hooks` block into `~/.claude/settings.json` and replace `$CLAUDE_PROJECT_DIR/packages/…` with the absolute path to this repo's bin.
 
-### Custom animations from the agent
-
-The same CLI has a `play` command that an agent can run to speak and move. It streams a WAV to [`POST /play`](api.md#post-play) with a timeline of moves, gaze and faces, prints the robot's reply when the clip ends, and exits 1 with the reason on any error:
-
-```bash
-node packages/tiny-engineer-claude-code/bin/tiny-engineer-claude-code.js play hello.wav \
-  --anim '[["preset","thinking"],["sleep",800],["move","head",0.6,300],["face","happy"]]'
-```
-
-`--anim-file dance.json` reads the timeline from a file. `--help` lists every step.
+### Speaking through the robot
 
-To let Claude use it on its own in any project, install the bundled skill. It explains how to make a clip with text-to-speech, write the timeline, and fix errors:
+The same CLI has a `play` command an agent can run to speak through the robot. It streams a WAV (16-bit mono PCM at 22050 Hz, from any text-to-speech) to [`POST /play`](api.md#post-play) while the robot runs `talking`, prints the robot's reply when the clip ends, and exits 1 with the reason on any error:
 
 ```bash
-ln -s "$PWD/packages/tiny-engineer-claude-code/skills/tiny-engineer-play" ~/.claude/skills/tiny-engineer-play
+espeak-ng -w /tmp/raw.wav "Build passed." && ffmpeg -y -loglevel error -i /tmp/raw.wav -ar 22050 -ac 1 -c:a pcm_s16le /tmp/clip.wav
+node packages/tiny-engineer-claude-code/bin/tiny-engineer-claude-code.js play /tmp/clip.wav
 ```
 
-Then ask Claude something like "have the robot congratulate me on the green build".
+`--name thinking` (or `typing`, `reading`, `none`) runs another animation for the clip.
 
 ### Smoke test
 
diff --git a/packages/tiny-engineer-claude-code/src/cli.js b/packages/tiny-engineer-claude-code/src/cli.js
index eddc6958..43b516fa 100644
--- a/packages/tiny-engineer-claude-code/src/cli.js
+++ b/packages/tiny-engineer-claude-code/src/cli.js
@@ -7,7 +7,7 @@ import { postAnim } from "./post.js";
 
 function printHelp() {
   console.log(`Usage: tiny-engineer-claude-code [options]
-       tiny-engineer-claude-code play <clip.wav> [--anim <json> | --anim-file <path>] [--url <base>]
+       tiny-engineer-claude-code play <clip.wav> [--name <animation>] [--url <base>]
 
 Claude Code hook helper: read event JSON from stdin, pick an animation, POST to the robot.
 
@@ -50,22 +50,13 @@ Event map:
 
 Play mode:
   Streams a 16-bit mono PCM WAV (at the robot's sample rate) to POST /play and
-  runs an optional timeline alongside it. Steps run in order; only "sleep"
-  advances time, so steps without a sleep between them start together:
-    ["sleep", ms]                 wait ms of playback
-    ["preset", name]              none, typing, reading, thinking or wakeup
-    ["move", servo, to, ms?]      head, neck, hand_left, hand_right or body to -1..1
-    ["eyes", mode]                idle, thinking, error, ... (an /anim name)
-    ["look", x, y, ms?]           gaze: x -1 screen left..1 right, y -1 up..1 down
-    ["open", amount, ms?]         eyelids, 0 closed to 1 open
-    ["blink"]
-    ["face", name]                idle, happy, laugh, wink, curious, thinking,
-                                  surprise, smug, sleepy, sleep, sad, cry, angry,
-                                  panic, shy or love
+  runs one animation while it plays: talking (default), typing, reading,
+  thinking or none. The robot then returns to the loop it was in.
   Prints the robot's JSON reply when the clip ends; exits 1 on any error.
 
 Examples:
-  tiny-engineer-claude-code play hello.wav --anim '[["preset","thinking"],["sleep",800],["move","head",0.6,300],["face","happy"]]'
+  tiny-engineer-claude-code play hello.wav
+  tiny-engineer-claude-code play hmm.wav --name thinking
   echo '{"hook_event_name":"Stop"}' | tiny-engineer-claude-code
   echo '{"hook_event_name":"PreToolUse","tool_name":"Read"}' | tiny-engineer-claude-code --url http://192.168.1.10
 `);
@@ -140,7 +131,7 @@ async function runPlay(argv) {
     const reply = await postPlay({
       baseUrl: opts.url ?? getBaseUrl(),
       wav,
-      anim: opts.anim,
+      name: opts.name,
       token: getToken(),
     });
     (reply.ok ? console.log : console.error)(reply.body);
diff --git a/packages/tiny-engineer-claude-code/src/play.js b/packages/tiny-engineer-claude-code/src/play.js
index 77a11f8b..b5173940 100644
--- a/packages/tiny-engineer-claude-code/src/play.js
+++ b/packages/tiny-engineer-claude-code/src/play.js
@@ -1,5 +1,3 @@
-import { readFileSync } from "node:fs";
-
 import { robotFetch } from "./post.js";
 
 // The robot answers once the clip has finished playing.
@@ -7,29 +5,19 @@ const PLAY_TIMEOUT_MS = 10 * 60 * 1000;
 
 /**
  * @param {string[]} argv arguments after `play`
- * @returns {{ wavPath?: string, anim?: string, url?: string, error?: string }}
+ * @returns {{ wavPath?: string, name?: string, url?: string, error?: string }}
  */
 export function parsePlayArgs(argv) {
-  /** @type {{ wavPath?: string, anim?: string, url?: string }} */
+  /** @type {{ wavPath?: string, name?: string, url?: string }} */
   const opts = {};
 
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
-    const value = argv[i + 1];
 
-    if (arg === "--anim" || arg === "--anim-file" || arg === "--url") {
+    if (arg === "--name" || arg === "--url") {
+      const value = argv[++i];
       if (!value) return { error: `${arg} requires a value` };
-      i++;
-      if (arg === "--url") {
-        opts.url = value;
-        continue;
-      }
-      if (opts.anim !== undefined) return { error: "use --anim or --anim-file, not both" };
-      try {
-        opts.anim = arg === "--anim" ? value : readFileSync(value, "utf8");
-      } catch (err) {
-        return { error: `cannot read ${value}: ${err.message}` };
-      }
+      opts[arg.slice(2)] = value;
       continue;
     }
     if (arg.startsWith("-") || opts.wavPath) return { error: `Unknown argument: ${arg}` };
@@ -37,33 +25,24 @@ export function parsePlayArgs(argv) {
   }
 
   if (!opts.wavPath) return { error: "play needs a WAV file" };
-
-  if (opts.anim !== undefined) {
-    try {
-      // One header line: drop the whitespace a file or pretty-printed JSON carries.
-      opts.anim = JSON.stringify(JSON.parse(opts.anim));
-    } catch {
-      return { error: "the timeline is not valid JSON" };
-    }
-  }
-
   return opts;
 }
 
 /**
- * POST a WAV to /play, with the timeline in X-Anim. Resolves with the robot's reply.
- * @param {{ baseUrl: string, wav: Uint8Array, anim?: string, token?: string | null }} request
+ * POST a WAV to /play (or /play/<name>). Resolves with the robot's reply.
+ * @param {{ baseUrl: string, wav: Uint8Array, name?: string, token?: string | null }} request
  * @returns {Promise<{ ok: boolean, status: number, body: string }>}
  */
-export async function postPlay({ baseUrl, wav, anim, token }) {
-  /** @type {Record<string, string>} */
-  const headers = { "Content-Type": "audio/wav" };
-  if (anim) headers["X-Anim"] = anim;
-
+export async function postPlay({ baseUrl, wav, name, token }) {
   const response = await robotFetch(
     baseUrl,
-    "/play",
-    { method: "POST", headers, body: wav, signal: AbortSignal.timeout(PLAY_TIMEOUT_MS) },
+    name ? `/play/${encodeURIComponent(name)}` : "/play",
+    {
+      method: "POST",
+      headers: { "Content-Type": "audio/wav" },
+      body: wav,
+      signal: AbortSignal.timeout(PLAY_TIMEOUT_MS),
+    },
     token,
   );
 
diff --git a/packages/tiny-engineer-claude-code/test/play.test.js b/packages/tiny-engineer-claude-code/test/play.test.js
index 2e8f6931..a61c2d84 100644
--- a/packages/tiny-engineer-claude-code/test/play.test.js
+++ b/packages/tiny-engineer-claude-code/test/play.test.js
@@ -1,33 +1,23 @@
 import test from "node:test";
 import assert from "node:assert/strict";
 import { createServer } from "node:http";
-import { mkdtempSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
 import { parsePlayArgs, postPlay } from "../src/play.js";
 
-test("a timeline file is squashed onto one header line", () => {
-  const dir = mkdtempSync(join(tmpdir(), "te-claude-code-play-"));
-  const file = join(dir, "dance.json");
-  writeFileSync(file, '[\n  ["preset", "typing"],\n  ["sleep", 500]\n]\n');
-
-  assert.deepEqual(parsePlayArgs(["clip.wav", "--anim-file", file]), {
+test("play reads the WAV, animation name and URL", () => {
+  assert.deepEqual(parsePlayArgs(["clip.wav", "--name", "thinking", "--url", "http://robot"]), {
     wavPath: "clip.wav",
-    anim: '[["preset","typing"],["sleep",500]]',
+    name: "thinking",
+    url: "http://robot",
   });
 });
 
 test("play rejects bad arguments before contacting the robot", () => {
-  assert.equal(parsePlayArgs(["--anim", "[]"]).error, "play needs a WAV file");
-  assert.equal(parsePlayArgs(["clip.wav", "--anim", "[[\"sleep\""]).error, "the timeline is not valid JSON");
-  assert.equal(
-    parsePlayArgs(["clip.wav", "--anim", "[]", "--anim-file", "x.json"]).error,
-    "use --anim or --anim-file, not both",
-  );
+  assert.equal(parsePlayArgs(["--name", "talking"]).error, "play needs a WAV file");
+  assert.equal(parsePlayArgs(["clip.wav", "--name"]).error, "--name requires a value");
   assert.equal(parsePlayArgs(["a.wav", "b.wav"]).error, "Unknown argument: b.wav");
 });
 
-test("postPlay streams the WAV with the timeline and token headers", async () => {
+test("postPlay streams the WAV to the named animation's route with the token", async () => {
   let received;
   const server = createServer((req, res) => {
     const chunks = [];
@@ -45,13 +35,12 @@ test("postPlay streams the WAV with the timeline and token headers", async () =>
     const reply = await postPlay({
       baseUrl: `http://127.0.0.1:${port}/`,
       wav: Buffer.from("RIFFdata"),
-      anim: '[["blink"]]',
+      name: "thinking",
       token: "secret",
     });
 
     assert.deepEqual(reply, { ok: true, status: 200, body: '{"ok":true,"played_ms":10}' });
-    assert.equal(received.url, "/play");
-    assert.equal(received.headers["x-anim"], '[["blink"]]');
+    assert.equal(received.url, "/play/thinking");
     assert.equal(received.headers.authorization, "Bearer secret");
     assert.equal(received.body.toString(), "RIFFdata");
   } finally {
diff --git a/platformio.ini b/platformio.ini
index 8eedd09f..f53919d5 100644
--- a/platformio.ini
+++ b/platformio.ini
@@ -23,14 +23,11 @@ lib_deps =
     adafruit/Adafruit PWM Servo Driver Library
     adafruit/Adafruit GFX Library
     adafruit/Adafruit SSD1306
-    bblanchon/ArduinoJson@^7.4.3
 
 build_flags =
     -D ARDUINO_USB_MODE=1
     -D ARDUINO_USB_CDC_ON_BOOT=1
     -D SSD1306_NO_SPLASH
-    ; Room for the X-Anim header on POST /play (about 250 steps).
-    -D WEBSERVER_MAX_LINE_LEN=8192
 
 board_build.partitions = partitions.csv
 board_build.filesystem = littlefs
@@ -61,13 +58,11 @@ extra_scripts =
 platform = native
 test_framework = unity
 test_build_src = true
-lib_deps = bblanchon/ArduinoJson@^7.4.3
 build_src_filter =
     -<**/*.*>
     +<settings/validate.cpp>
     +<display/eyes/styles/eye_style_ids.cpp>
     +<audio/wav_parser.cpp>
-    +<animation/timeline.cpp>
 build_flags = -std=c++17 -Iinclude -Isrc
 
 ; Opt-in OLED-only application. Building does not upload or change robot settings.
diff --git a/src/animation/controller.cpp b/src/animation/controller.cpp
index c2c6fab6..87e7bfbd 100644
--- a/src/animation/controller.cpp
+++ b/src/animation/controller.cpp
@@ -109,6 +109,10 @@ void setAnimation(AnimationId id) {
   serialLogPrintln(holdLeftMs);
 }
 
+void setAnimationImmediately(AnimationId id) {
+  applyAnimation(id, millis());
+}
+
 void finishAnimation(uint32_t nowMs) {
   applyAnimation(AnimationId::None, nowMs);
 }
diff --git a/src/http/index_page.cpp b/src/http/index_page.cpp
index 15230a79..7bcd877f 100644
--- a/src/http/index_page.cpp
+++ b/src/http/index_page.cpp
@@ -237,7 +237,7 @@ body:not(.setup-mode) #setup-wizard{display:none!important}
 <tr><td>POST</td><td><code>/settings/reset</code></td><td>Factory reset all settings to defaults</td></tr>
 <tr><td>GET</td><td><code>/anim</code></td><td>Current animation name</td></tr>
 <tr><td>POST</td><td><code>/anim</code></td><td>Set animation (see parameters below)</td></tr>
-<tr><td>POST</td><td><code>/play</code></td><td>Stream a WAV with an optional animation timeline (see parameters below)</td></tr>
+<tr><td>POST</td><td><code>/play</code></td><td>Stream a WAV while an animation runs (see parameters below)</td></tr>
 <tr><td>POST</td><td><code>/test/audio</code></td><td>Play tone test</td></tr>
 <tr><td>POST</td><td><code>/test/audio/bell</code></td><td>Play bell WAV from LittleFS</td></tr>
 <tr><td>POST</td><td><code>/test/screen</code></td><td>OLED demo</td></tr>
@@ -276,6 +276,7 @@ body:not(.setup-mode) #setup-wizard{display:none!important}
 <tr><td><code>typing</code></td><td>Typing gesture</td></tr>
 <tr><td><code>reading</code></td><td>Reading gesture</td></tr>
 <tr><td><code>thinking</code></td><td>Thinking gesture</td></tr>
+<tr><td><code>talking</code></td><td>Speaking gesture</td></tr>
 <tr><td><code>ring</code></td><td>One-shot bell gesture</td></tr>
 <tr><td><code>welcome</code></td><td>One-shot hello gesture</td></tr>
 <tr><td><code>attention</code></td><td>Input-request gesture + audio</td></tr>
@@ -285,17 +286,14 @@ body:not(.setup-mode) #setup-wizard{display:none!important}
 <tr><td><code>wakeup</code></td><td>One-shot sleep-inertia wake</td></tr>
 <tr><td><code>sleep</code></td><td>Close eyes and sleep</td></tr>
 </table>
-<p>POST <code>/play</code> &mdash; body: 16-bit mono PCM WAV at 22050 Hz. Optional header <code>X-Anim</code>: JSON array of steps, run in order; only <code>sleep</code> advances time:</p>
+<p>POST <code>/play</code> or <code>/play/{name}</code> &mdash; body: 16-bit mono PCM WAV at 22050 Hz. <code>name</code> runs while the clip plays:</p>
 <table>
-<tr><th>Step</th><th>Values</th></tr>
-<tr><td><code>["sleep", ms]</code></td><td>0&ndash;600000 ms of playback</td></tr>
-<tr><td><code>["preset", name]</code></td><td><code>none</code>, <code>typing</code>, <code>reading</code>, <code>thinking</code>, <code>wakeup</code></td></tr>
-<tr><td><code>["move", servo, to, ms?]</code></td><td><code>head</code>, <code>neck</code>, <code>hand_left</code>, <code>hand_right</code>, <code>body</code>; <code>to</code> &minus;1&ndash;1</td></tr>
-<tr><td><code>["eyes", mode]</code></td><td><code>idle</code> or a <code>/anim</code> name</td></tr>
-<tr><td><code>["look", x, y, ms?]</code></td><td><code>x</code> &minus;1 left to 1 right, <code>y</code> &minus;1 up to 1 down</td></tr>
-<tr><td><code>["open", amount, ms?]</code></td><td>0&ndash;1</td></tr>
-<tr><td><code>["blink"]</code></td><td></td></tr>
-<tr><td><code>["face", name]</code></td><td><code>idle</code>, <code>happy</code>, <code>laugh</code>, <code>wink</code>, <code>curious</code>, <code>thinking</code>, <code>surprise</code>, <code>smug</code>, <code>sleepy</code>, <code>sleep</code>, <code>sad</code>, <code>cry</code>, <code>angry</code>, <code>panic</code>, <code>shy</code>, <code>love</code></td></tr>
+<tr><th>Value</th><th>Description</th></tr>
+<tr><td><code>talking</code></td><td>Default</td></tr>
+<tr><td><code>typing</code></td><td>Typing gesture</td></tr>
+<tr><td><code>reading</code></td><td>Reading gesture</td></tr>
+<tr><td><code>thinking</code></td><td>Thinking gesture</td></tr>
+<tr><td><code>none</code></td><td>Idle pose</td></tr>
 </table>
 <p>POST <code>/test/servo</code> &mdash; query params:</p>
 <table>
diff --git a/src/http/json.cpp b/src/http/json.cpp
index b77f0632..910225e8 100644
--- a/src/http/json.cpp
+++ b/src/http/json.cpp
@@ -8,7 +8,7 @@ namespace {
 
 void sendCorsHeaders(WebServer& server) {
   server.sendHeader("Access-Control-Allow-Origin", "*");
-  server.sendHeader("Access-Control-Allow-Headers", "Authorization, X-Anim");
+  server.sendHeader("Access-Control-Allow-Headers", "Authorization");
   server.sendHeader(
     "Access-Control-Allow-Methods",
     "GET, POST, OPTIONS"
diff --git a/src/http/play_handlers.cpp b/src/http/play_handlers.cpp
index 322ae50e..a1196184 100644
--- a/src/http/play_handlers.cpp
+++ b/src/http/play_handlers.cpp
@@ -5,27 +5,40 @@
 #include <cstdio>
 #include <optional>
 
-#include "animation/timeline.h"
-#include "animation/timeline_player.h"
+#include "animation.h"
 #include "audio/audio.h"
 #include "audio/wav_parser.h"
 #include "http/json.h"
 #include "pins.h"
 #include "robot_tick.h"
-#include "sleep.h"
 #include "settings/settings.h"
 #include "serial_log.h"
+#include "sleep.h"
 
 namespace {
 
+// Animations with no sound of their own, so they cannot talk over the clip.
+bool playableDuringClip(AnimationId id) {
+  switch (id) {
+    case AnimationId::Talking:
+    case AnimationId::Typing:
+    case AnimationId::Reading:
+    case AnimationId::Thinking:
+    case AnimationId::None:
+      return true;
+    default:
+      return false;
+  }
+}
+
 // One POST /play request. loop() is blocked while the body streams, so the
 // session runs tickRobot() between speaker writes.
 class PlaySession : public WavStreamParser::Sink {
 public:
   void begin(WebServer& server) {
     parser_.reset();
-    player_.reset();
     rejectCode_ = 0;
+    started_ = false;
 
     if (!settingsWifiConfigured()) {
       reject(503, "wifi not configured");
@@ -37,25 +50,16 @@ class PlaySession : public WavStreamParser::Sink {
       return;
     }
 
-    stopAllWavPlayback();
-    parser_.emplace(SAMPLE_RATE, *this);
-    serialLogPrintln("[play] start");
-
-    const String& header = server.header("X-Anim");
+    const String name = server.pathArg(0);
 
-    if (header.length() == 0) {
+    if (!parseAnimationName(name.length() > 0 ? name.c_str() : "talking", animation_) || !playableDuringClip(animation_)) {
+      reject(400, "name must be talking, typing, reading, thinking or none");
       return;
     }
 
-    std::optional<Timeline> timeline = Timeline::parse(header.c_str(), header.length(), TimelinePlayer::names(), error_, sizeof(error_));
-
-    if (!timeline) {
-      reject(400, error_);
-      return;
-    }
-
-    player_.emplace(std::move(*timeline));
-    player_->advance(0);
+    stopAllWavPlayback();
+    parser_.emplace(SAMPLE_RATE, *this);
+    serialLogPrintln("[play] start");
   }
 
   void feed(const uint8_t* bytes, size_t length) {
@@ -65,15 +69,16 @@ class PlaySession : public WavStreamParser::Sink {
   }
 
   void end() {
-    if (parser_) {
-      parser_->finish();
-      serialLogPrint("[play] end ms=");
-      serialLogPrintln(playedMs());
+    if (!parser_) {
+      return;
     }
 
-    if (player_) {
-      player_->finish();
-      player_.reset();
+    parser_->finish();
+    serialLogPrint("[play] end ms=");
+    serialLogPrintln(playedMs());
+
+    if (started_) {
+      setAnimationImmediately(animationIsContinuous(previous_) ? previous_ : AnimationId::None);
     }
   }
 
@@ -94,22 +99,25 @@ class PlaySession : public WavStreamParser::Sink {
   }
 
   void onPcm(const int16_t* samples, size_t count) override {
-    writeMonoToSpeaker(samples, count);
-
-    if (player_) {
-      player_->advance(playedMs());
+    if (!started_) {
+      // The format is known good by now, so the robot only moves for clips it can play.
+      started_ = true;
+      previous_ = getAnimation();
+      setAnimationImmediately(animation_);
     }
 
+    writeMonoToSpeaker(samples, count);
     noteActivity(millis());
     tickRobot();
   }
 
 private:
   std::optional<WavStreamParser> parser_;
-  std::optional<TimelinePlayer> player_;
+  AnimationId animation_ = AnimationId::Talking;
+  AnimationId previous_ = AnimationId::None;
+  bool started_ = false;
   int rejectCode_ = 0;
-  char error_[96] = {};
-  char body_[128] = {};
+  char body_[96] = {};
 
   void reject(int code, const char* message) {
     rejectCode_ = code;
diff --git a/src/http/routes.cpp b/src/http/routes.cpp
index 5c63467e..cbf0c409 100644
--- a/src/http/routes.cpp
+++ b/src/http/routes.cpp
@@ -2,6 +2,7 @@
 
 #include <Arduino.h>
 #include <WebServer.h>
+#include <uri/UriBraces.h>
 
 #include "http/anim_handlers.h"
 #include "http/health_handlers.h"
@@ -84,12 +85,19 @@ void registerHttpRoutes() {
   server.on("/anim", HTTP_POST, []() {
     httpWithWifiAndApiAuth(httpServer(), handleAnimPost);
   });
+  // /play runs `talking`; /play/<name> picks another animation for the clip.
   server.on(
     "/play",
     HTTP_POST,
     []() { handlePlayDone(httpServer()); },
     []() { handlePlayBody(httpServer()); }
   );
+  server.on(
+    UriBraces("/play/{}"),
+    HTTP_POST,
+    []() { handlePlayDone(httpServer()); },
+    []() { handlePlayBody(httpServer()); }
+  );
   server.on("/settings", HTTP_GET, []() {
     httpWithApiAuth(httpServer(), handleSettingsGet);
   });
diff --git a/src/http/settings_handlers.cpp b/src/http/settings_handlers.cpp
index 909e4d7a..9889c071 100644
--- a/src/http/settings_handlers.cpp
+++ b/src/http/settings_handlers.cpp
@@ -662,6 +662,6 @@ void handleSettingsReset(WebServer& server) {
 }
 
 bool isSettingsOrAnimPath(const String& uri) {
-  return uri == "/anim" || uri == "/play" || uri == "/settings" || uri == "/settings/reset" ||
+  return uri == "/anim" || uri == "/play" || uri.startsWith("/play/") || uri == "/settings" || uri == "/settings/reset" ||
          uri == "/auth" || uri == "/setup/servo";
 }

From 508459a33ef02c4866fcb89ce9e5bb3dcd9a8ca2 Mon Sep 17 00:00:00 2001
From: shodan <mega@ioexception.at>
Date: Sun, 4 Oct 2026 19:27:24 +0200
Subject: [PATCH 18/21] fix(http): only read the /play path argument on the
 named route

WebServer's pathArg() asserts when the matched route has no path
arguments, so a plain POST /play rebooted the robot. Each route now tells
the handler whether it carries a name.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VYDrnWNM6nbcQ1nx8aua93
---
 src/http/play_handlers.cpp | 10 +++++-----
 src/http/play_handlers.h   |  5 +++--
 src/http/routes.cpp        |  4 ++--
 3 files changed, 10 insertions(+), 9 deletions(-)

diff --git a/src/http/play_handlers.cpp b/src/http/play_handlers.cpp
index a1196184..e290c738 100644
--- a/src/http/play_handlers.cpp
+++ b/src/http/play_handlers.cpp
@@ -35,7 +35,7 @@ bool playableDuringClip(AnimationId id) {
 // session runs tickRobot() between speaker writes.
 class PlaySession : public WavStreamParser::Sink {
 public:
-  void begin(WebServer& server) {
+  void begin(WebServer& server, bool named) {
     parser_.reset();
     rejectCode_ = 0;
     started_ = false;
@@ -50,9 +50,9 @@ class PlaySession : public WavStreamParser::Sink {
       return;
     }
 
-    const String name = server.pathArg(0);
+    const String name = named ? server.pathArg(0) : String("talking");
 
-    if (!parseAnimationName(name.length() > 0 ? name.c_str() : "talking", animation_) || !playableDuringClip(animation_)) {
+    if (!parseAnimationName(name.c_str(), animation_) || !playableDuringClip(animation_)) {
       reject(400, "name must be talking, typing, reading, thinking or none");
       return;
     }
@@ -137,12 +137,12 @@ PlaySession g_session;
 
 }  // namespace
 
-void handlePlayBody(WebServer& server) {
+void handlePlayBody(WebServer& server, bool named) {
   HTTPRaw& raw = server.raw();
 
   switch (raw.status) {
     case RAW_START:
-      g_session.begin(server);
+      g_session.begin(server, named);
       break;
     case RAW_WRITE:
       g_session.feed(raw.buf, raw.currentSize);
diff --git a/src/http/play_handlers.h b/src/http/play_handlers.h
index f22dc8f9..9fbbf9f3 100644
--- a/src/http/play_handlers.h
+++ b/src/http/play_handlers.h
@@ -2,7 +2,8 @@
 
 #include <WebServer.h>
 
-// Called for each slice of the request body as it arrives.
-void handlePlayBody(WebServer& server);
+// Called for each slice of the request body as it arrives. `named` is true on
+// the /play/{name} route; pathArg() asserts on a route without path arguments.
+void handlePlayBody(WebServer& server, bool named);
 // Called once the whole body has been consumed.
 void handlePlayDone(WebServer& server);
diff --git a/src/http/routes.cpp b/src/http/routes.cpp
index cbf0c409..cdfddd00 100644
--- a/src/http/routes.cpp
+++ b/src/http/routes.cpp
@@ -90,13 +90,13 @@ void registerHttpRoutes() {
     "/play",
     HTTP_POST,
     []() { handlePlayDone(httpServer()); },
-    []() { handlePlayBody(httpServer()); }
+    []() { handlePlayBody(httpServer(), false); }
   );
   server.on(
     UriBraces("/play/{}"),
     HTTP_POST,
     []() { handlePlayDone(httpServer()); },
-    []() { handlePlayBody(httpServer()); }
+    []() { handlePlayBody(httpServer(), true); }
   );
   server.on("/settings", HTTP_GET, []() {
     httpWithApiAuth(httpServer(), handleSettingsGet);

From cf775e2abc5379818c57f0371392083bbd32065f Mon Sep 17 00:00:00 2001
From: shodan <mega@ioexception.at>
Date: Sun, 4 Oct 2026 19:32:41 +0200
Subject: [PATCH 19/21] refactor(http): derive the /play allowlist from the
 animation registry

/play accepts none and any continuous animation, since none of those
play a sound of their own, instead of a hand-kept list. The name comes
from the request path, so the two routes share one handler. The WAV
parser only hands over full batches until the body ends, which cuts the
speaker writes per second by about 7%. Talking parks its gesture hand
on a transition, and postPlay drops a status field nothing reads.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VYDrnWNM6nbcQ1nx8aua93
---
 .../tiny-engineer-claude-code/src/play.js     |  4 +--
 .../test/play.test.js                         |  2 +-
 src/animation/registry.cpp                    |  4 +--
 src/animation/talking.cpp                     |  3 +-
 src/audio/wav_parser.cpp                      | 12 ++------
 src/http/play_handlers.cpp                    | 30 +++++++------------
 src/http/play_handlers.h                      |  5 ++--
 src/http/routes.cpp                           |  4 +--
 src/http/settings_handlers.cpp                |  3 +-
 9 files changed, 26 insertions(+), 41 deletions(-)

diff --git a/packages/tiny-engineer-claude-code/src/play.js b/packages/tiny-engineer-claude-code/src/play.js
index b5173940..6b16b3d4 100644
--- a/packages/tiny-engineer-claude-code/src/play.js
+++ b/packages/tiny-engineer-claude-code/src/play.js
@@ -31,7 +31,7 @@ export function parsePlayArgs(argv) {
 /**
  * POST a WAV to /play (or /play/<name>). Resolves with the robot's reply.
  * @param {{ baseUrl: string, wav: Uint8Array, name?: string, token?: string | null }} request
- * @returns {Promise<{ ok: boolean, status: number, body: string }>}
+ * @returns {Promise<{ ok: boolean, body: string }>}
  */
 export async function postPlay({ baseUrl, wav, name, token }) {
   const response = await robotFetch(
@@ -46,5 +46,5 @@ export async function postPlay({ baseUrl, wav, name, token }) {
     token,
   );
 
-  return { ok: response.ok, status: response.status, body: await response.text() };
+  return { ok: response.ok, body: await response.text() };
 }
diff --git a/packages/tiny-engineer-claude-code/test/play.test.js b/packages/tiny-engineer-claude-code/test/play.test.js
index a61c2d84..5618af6f 100644
--- a/packages/tiny-engineer-claude-code/test/play.test.js
+++ b/packages/tiny-engineer-claude-code/test/play.test.js
@@ -39,7 +39,7 @@ test("postPlay streams the WAV to the named animation's route with the token", a
       token: "secret",
     });
 
-    assert.deepEqual(reply, { ok: true, status: 200, body: '{"ok":true,"played_ms":10}' });
+    assert.deepEqual(reply, { ok: true, body: '{"ok":true,"played_ms":10}' });
     assert.equal(received.url, "/play/thinking");
     assert.equal(received.headers.authorization, "Bearer secret");
     assert.equal(received.body.toString(), "RIFFdata");
diff --git a/src/animation/registry.cpp b/src/animation/registry.cpp
index 78eb7600..2c3c3ce7 100644
--- a/src/animation/registry.cpp
+++ b/src/animation/registry.cpp
@@ -9,9 +9,9 @@
 #include "animation/dead.h"
 #include "animation/error.h"
 #include "animation/reading.h"
-#include "animation/talking.h"
 #include "animation/ring.h"
 #include "animation/sleep_anim.h"
+#include "animation/talking.h"
 #include "animation/thinking.h"
 #include "animation/typing.h"
 #include "animation/util.h"
@@ -23,8 +23,8 @@
 #include "display/eyes/modes/error.h"
 #include "display/eyes/modes/idle.h"
 #include "display/eyes/modes/reading.h"
-#include "display/eyes/modes/talking.h"
 #include "display/eyes/modes/ring.h"
+#include "display/eyes/modes/talking.h"
 #include "display/eyes/modes/thinking.h"
 #include "display/eyes/modes/typing.h"
 #include "display/eyes/modes/wakeup.h"
diff --git a/src/animation/talking.cpp b/src/animation/talking.cpp
index 0384fd08..cddad4ae 100644
--- a/src/animation/talking.cpp
+++ b/src/animation/talking.cpp
@@ -7,7 +7,6 @@
 #include "hardware/servo_wrapper.h"
 #include "servos.h"
 
-using anim::parkTorso;
 using anim::randRangeMs;
 using anim::randUnit;
 using anim::stopAnimServos;
@@ -62,7 +61,7 @@ void updateTalking(uint32_t now) {
 
   if (hasPendingAnimation() && !g_poseFrozen) {
     g_poseFrozen = true;
-    parkTorso(anim::TRANSITION_TORSO_SPEED_DEG_S);
+    anim::parkForTransition();
   }
 
   if (g_poseFrozen) {
diff --git a/src/audio/wav_parser.cpp b/src/audio/wav_parser.cpp
index a7cfb164..da928179 100644
--- a/src/audio/wav_parser.cpp
+++ b/src/audio/wav_parser.cpp
@@ -80,8 +80,6 @@ void WavStreamParser::feed(const uint8_t* bytes, size_t length) {
     bytes += used;
     length -= used;
   }
-
-  flush();
 }
 
 void WavStreamParser::finish() {
@@ -157,13 +155,9 @@ void WavStreamParser::parseFormat() {
   }
 
   if (format != kFormatPcm || channels != 1 || bits != 16 || rate != sampleRate_) {
-    snprintf(
-      message_,
-      sizeof(message_),
-      "expected 16-bit mono PCM at %lu Hz",
-      static_cast<unsigned long>(sampleRate_)
-    );
-    state_ = State::Failed;
+    char expected[48];
+    snprintf(expected, sizeof(expected), "expected 16-bit mono PCM at %lu Hz", static_cast<unsigned long>(sampleRate_));
+    fail(expected);
     return;
   }
 
diff --git a/src/http/play_handlers.cpp b/src/http/play_handlers.cpp
index e290c738..55c13728 100644
--- a/src/http/play_handlers.cpp
+++ b/src/http/play_handlers.cpp
@@ -17,25 +17,13 @@
 
 namespace {
 
-// Animations with no sound of their own, so they cannot talk over the clip.
-bool playableDuringClip(AnimationId id) {
-  switch (id) {
-    case AnimationId::Talking:
-    case AnimationId::Typing:
-    case AnimationId::Reading:
-    case AnimationId::Thinking:
-    case AnimationId::None:
-      return true;
-    default:
-      return false;
-  }
-}
+constexpr size_t kPlayPrefixLen = sizeof("/play/") - 1;
 
 // One POST /play request. loop() is blocked while the body streams, so the
 // session runs tickRobot() between speaker writes.
 class PlaySession : public WavStreamParser::Sink {
 public:
-  void begin(WebServer& server, bool named) {
+  void begin(WebServer& server) {
     parser_.reset();
     rejectCode_ = 0;
     started_ = false;
@@ -50,9 +38,13 @@ class PlaySession : public WavStreamParser::Sink {
       return;
     }
 
-    const String name = named ? server.pathArg(0) : String("talking");
+    // "/play" or "/play/<name>"; pathArg() would assert on the route without a name.
+    const String uri = server.uri();
+    const char* name = uri.length() > kPlayPrefixLen ? uri.c_str() + kPlayPrefixLen : "talking";
 
-    if (!parseAnimationName(name.c_str(), animation_) || !playableDuringClip(animation_)) {
+    // Continuous animations and none play no sound of their own, so they cannot talk over the clip.
+    if (!parseAnimationName(name, animation_) ||
+        (animation_ != AnimationId::None && !animationIsContinuous(animation_))) {
       reject(400, "name must be talking, typing, reading, thinking or none");
       return;
     }
@@ -63,7 +55,7 @@ class PlaySession : public WavStreamParser::Sink {
   }
 
   void feed(const uint8_t* bytes, size_t length) {
-    if (rejectCode_ == 0 && parser_) {
+    if (parser_) {
       parser_->feed(bytes, length);
     }
   }
@@ -137,12 +129,12 @@ PlaySession g_session;
 
 }  // namespace
 
-void handlePlayBody(WebServer& server, bool named) {
+void handlePlayBody(WebServer& server) {
   HTTPRaw& raw = server.raw();
 
   switch (raw.status) {
     case RAW_START:
-      g_session.begin(server, named);
+      g_session.begin(server);
       break;
     case RAW_WRITE:
       g_session.feed(raw.buf, raw.currentSize);
diff --git a/src/http/play_handlers.h b/src/http/play_handlers.h
index 9fbbf9f3..f22dc8f9 100644
--- a/src/http/play_handlers.h
+++ b/src/http/play_handlers.h
@@ -2,8 +2,7 @@
 
 #include <WebServer.h>
 
-// Called for each slice of the request body as it arrives. `named` is true on
-// the /play/{name} route; pathArg() asserts on a route without path arguments.
-void handlePlayBody(WebServer& server, bool named);
+// Called for each slice of the request body as it arrives.
+void handlePlayBody(WebServer& server);
 // Called once the whole body has been consumed.
 void handlePlayDone(WebServer& server);
diff --git a/src/http/routes.cpp b/src/http/routes.cpp
index cdfddd00..cbf0c409 100644
--- a/src/http/routes.cpp
+++ b/src/http/routes.cpp
@@ -90,13 +90,13 @@ void registerHttpRoutes() {
     "/play",
     HTTP_POST,
     []() { handlePlayDone(httpServer()); },
-    []() { handlePlayBody(httpServer(), false); }
+    []() { handlePlayBody(httpServer()); }
   );
   server.on(
     UriBraces("/play/{}"),
     HTTP_POST,
     []() { handlePlayDone(httpServer()); },
-    []() { handlePlayBody(httpServer(), true); }
+    []() { handlePlayBody(httpServer()); }
   );
   server.on("/settings", HTTP_GET, []() {
     httpWithApiAuth(httpServer(), handleSettingsGet);
diff --git a/src/http/settings_handlers.cpp b/src/http/settings_handlers.cpp
index 9889c071..ea730a61 100644
--- a/src/http/settings_handlers.cpp
+++ b/src/http/settings_handlers.cpp
@@ -662,6 +662,7 @@ void handleSettingsReset(WebServer& server) {
 }
 
 bool isSettingsOrAnimPath(const String& uri) {
-  return uri == "/anim" || uri == "/play" || uri.startsWith("/play/") || uri == "/settings" || uri == "/settings/reset" ||
+  return uri == "/anim" || uri == "/play" || uri.startsWith("/play/") ||
+         uri == "/settings" || uri == "/settings/reset" ||
          uri == "/auth" || uri == "/setup/servo";
 }

From 25c5be782d906d1322e6a702a601d08e80d65da1 Mon Sep 17 00:00:00 2001
From: shodan <mega@ioexception.at>
Date: Tue, 6 Oct 2026 00:06:47 +0200
Subject: [PATCH 20/21] feat(integrations): add a tiny-engineer-play skill for
 every agent platform

skills/tiny-engineer-play is a plain Agent Skill (SKILL.md plus a curl
script) that Claude Code, Cursor and Antigravity all load from their
skill folders. It tells the agent to make a 22050 Hz clip with any
text-to-speech and send it to POST /play, optionally naming the
animation, and maps each /play error to its fix.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VYDrnWNM6nbcQ1nx8aua93
---
 AGENTS.md                              |  3 +-
 docs/integration.md                    | 10 +++++++
 skills/tiny-engineer-play/SKILL.md     | 38 ++++++++++++++++++++++++++
 skills/tiny-engineer-play/scripts/play | 25 +++++++++++++++++
 4 files changed, 75 insertions(+), 1 deletion(-)
 create mode 100644 skills/tiny-engineer-play/SKILL.md
 create mode 100755 skills/tiny-engineer-play/scripts/play

diff --git a/AGENTS.md b/AGENTS.md
index d5bd0c66..73fb5895 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -12,6 +12,7 @@ Tiny Engineer is an open-source ESP32-C3 Wi-Fi desk robot: 3D-printed mechanics,
 | --- | --- |
 | `src/`, `include/`, `lib/`, `data/` | Firmware (PlatformIO) |
 | `packages/` | HTTP / hook CLIs (Cursor, Antigravity, Claude Code, …) — scope `integrations` |
+| `skills/` | Agent skills shared by Claude Code, Cursor and Antigravity — scope `integrations` |
 | `3d_models/` | CAD and printables (CERN-OHL-S) |
 | `mods/` | Optional mods; models under `mods/<name>/3d_models/` (CERN-OHL-S) |
 | `hardware/` | KiCad boards (CERN-OHL-S) |
@@ -62,7 +63,7 @@ HTML index: one-line route descriptions only (except supported-parameter lists).
 Format: `type(scope): summary` (imperative, lowercase type, no trailing period; PR title same).
 
 Scopes: `firmware`, `http`, `settings`, `anim`, `servos`, `wifi`, `integrations`, `cad`, `mods`, `pcb`, `docs`, `scripts`, `ci`.  
-`integrations` = anything under `packages/`. Do not add a new scope per package.  
+`integrations` = anything under `packages/` or `skills/`. Do not add a new scope per package.  
 `mods` = anything under `mods/`. Name the mod in the summary. Do not add a new scope per mod.
 
 Breaking rules, SemVer mapping, and examples: [CONTRIBUTING.md](CONTRIBUTING.md).
diff --git a/docs/integration.md b/docs/integration.md
index d82589d2..ad19045f 100644
--- a/docs/integration.md
+++ b/docs/integration.md
@@ -249,6 +249,16 @@ node packages/tiny-engineer-claude-code/bin/tiny-engineer-claude-code.js play /t
 
 `--name thinking` (or `typing`, `reading`, `none`) runs another animation for the clip.
 
+To let an agent do this on its own, install the shared [`tiny-engineer-play`](../skills/tiny-engineer-play/SKILL.md) skill. It needs only `curl` and works the same in Claude Code, Cursor and Antigravity:
+
+```bash
+ln -s "$PWD/skills/tiny-engineer-play" ~/.claude/skills/tiny-engineer-play            # Claude Code
+ln -s "$PWD/skills/tiny-engineer-play" ~/.cursor/skills/tiny-engineer-play            # Cursor
+ln -s "$PWD/skills/tiny-engineer-play" ~/.gemini/antigravity/skills/tiny-engineer-play  # Antigravity
+```
+
+Then ask the agent something like "have the robot tell me the build passed".
+
 ### Smoke test
 
 ```bash
diff --git a/skills/tiny-engineer-play/SKILL.md b/skills/tiny-engineer-play/SKILL.md
new file mode 100644
index 00000000..57b13f29
--- /dev/null
+++ b/skills/tiny-engineer-play/SKILL.md
@@ -0,0 +1,38 @@
+---
+name: tiny-engineer-play
+description: Make the Tiny Engineer desk robot say something out loud through its speaker while it gestures, via POST /play. Use whenever the user asks the robot to speak, announce or celebrate a result, greet them, or "tell me through the robot", and when debugging /play errors such as 415 "expected 16-bit mono PCM" or 400 "name must be ...".
+---
+
+# Tiny Engineer: speak through the robot
+
+The robot plays a WAV clip on its speaker while it runs an animation, then goes back to what it was doing. Clips must be 16-bit mono PCM at 22050 Hz.
+
+## 1. Make the clip
+
+Use any text-to-speech the machine has, then convert it with ffmpeg:
+
+```bash
+espeak-ng -w /tmp/te-raw.wav "Build passed. Ship it!"                                        # Linux
+say --file-format=WAVE --data-format=LEI16@22050 -o /tmp/te-raw.wav "Build passed. Ship it!"  # macOS
+ffmpeg -y -loglevel error -i /tmp/te-raw.wav -ar 22050 -ac 1 -c:a pcm_s16le /tmp/te-clip.wav
+```
+
+Keep clips short (a few seconds up to about 20 s): the robot handles one request at a time, so the hooks that animate it during normal work wait while a clip plays.
+
+## 2. Play it
+
+```bash
+<this skill's base directory>/scripts/play /tmp/te-clip.wav            # robot runs "talking"
+<this skill's base directory>/scripts/play /tmp/te-clip.wav thinking   # or typing, reading, none
+```
+
+It reads `TINY_ENGINEER_URL` (default `http://tiny-engineer.local`) and `TINY_ENGINEER_TOKEN` from the environment, prints the robot's JSON reply when the clip ends, and exits 1 with the reason on any error. It needs `curl`.
+
+## Errors
+
+| Reply | Fix |
+| --- | --- |
+| `415 expected 16-bit mono PCM at N Hz` | Re-run the `ffmpeg` step with `-ar N` |
+| `400 name must be ...` | Use `talking`, `typing`, `reading`, `thinking` or `none` |
+| `401 unauthorized` | Set `TINY_ENGINEER_TOKEN` to the robot's `access_token` |
+| `robot unreachable` | Check `TINY_ENGINEER_URL`; the robot must be on the same network |
diff --git a/skills/tiny-engineer-play/scripts/play b/skills/tiny-engineer-play/scripts/play
new file mode 100755
index 00000000..84155665
--- /dev/null
+++ b/skills/tiny-engineer-play/scripts/play
@@ -0,0 +1,25 @@
+#!/bin/sh
+# Usage: play <clip.wav> [talking|typing|reading|thinking|none]
+# Streams the clip to the robot's POST /play and prints its JSON reply; exits 1 on any error.
+set -u
+
+clip=${1:?usage: play <clip.wav> [animation]}
+name=${2:-}
+url=${TINY_ENGINEER_URL:-http://tiny-engineer.local}
+url=${url%/}/play${name:+/$name}
+
+[ -r "$clip" ] || { echo "cannot read $clip" >&2; exit 1; }
+
+set -- --silent --show-error --connect-timeout 5 --max-time 600 -X POST -H 'Content-Type: audio/wav' --data-binary "@$clip"
+[ -n "${TINY_ENGINEER_TOKEN:-}" ] && set -- "$@" -H "Authorization: Bearer $TINY_ENGINEER_TOKEN"
+
+reply=$(curl "$@" -w '\n%{http_code}' "$url") || { echo "robot unreachable at $url" >&2; exit 1; }
+status=${reply##*
+}
+body=${reply%
+*}
+
+case $status in
+  2??) echo "$body" ;;
+  *) echo "$body" >&2; exit 1 ;;
+esac

From e8f32cdb8ce9dc1dfe60d170859b6bfcf683bbb9 Mon Sep 17 00:00:00 2001
From: shodan <mega@ioexception.at>
Date: Tue, 6 Oct 2026 08:51:03 +0200
Subject: [PATCH 21/21] fix(integrations): harden /play inputs and resume
 talking after a cancelled switch

- The skill's play script only puts a bare lowercase animation name into
  the URL, so a name like ../settings/reset cannot reach another route.
- The CLI's --name and --url no longer take the next flag as their value.
- Talking resumes moving when a pending switch is cancelled by asking for
  talking again, instead of staying frozen.
- The skill install steps create each platform's skill folder first.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VYDrnWNM6nbcQ1nx8aua93
---
 docs/integration.md                               |  6 +++---
 packages/tiny-engineer-claude-code/src/play.js    |  2 +-
 .../tiny-engineer-claude-code/test/play.test.js   |  1 +
 skills/tiny-engineer-play/scripts/play            |  6 ++++++
 src/animation/talking.cpp                         | 15 +++++++++++----
 5 files changed, 22 insertions(+), 8 deletions(-)

diff --git a/docs/integration.md b/docs/integration.md
index ad19045f..ea7ad410 100644
--- a/docs/integration.md
+++ b/docs/integration.md
@@ -252,9 +252,9 @@ node packages/tiny-engineer-claude-code/bin/tiny-engineer-claude-code.js play /t
 To let an agent do this on its own, install the shared [`tiny-engineer-play`](../skills/tiny-engineer-play/SKILL.md) skill. It needs only `curl` and works the same in Claude Code, Cursor and Antigravity:
 
 ```bash
-ln -s "$PWD/skills/tiny-engineer-play" ~/.claude/skills/tiny-engineer-play            # Claude Code
-ln -s "$PWD/skills/tiny-engineer-play" ~/.cursor/skills/tiny-engineer-play            # Cursor
-ln -s "$PWD/skills/tiny-engineer-play" ~/.gemini/antigravity/skills/tiny-engineer-play  # Antigravity
+mkdir -p ~/.claude/skills && ln -s "$PWD/skills/tiny-engineer-play" ~/.claude/skills/                         # Claude Code
+mkdir -p ~/.cursor/skills && ln -s "$PWD/skills/tiny-engineer-play" ~/.cursor/skills/                         # Cursor
+mkdir -p ~/.gemini/antigravity/skills && ln -s "$PWD/skills/tiny-engineer-play" ~/.gemini/antigravity/skills/  # Antigravity
 ```
 
 Then ask the agent something like "have the robot tell me the build passed".
diff --git a/packages/tiny-engineer-claude-code/src/play.js b/packages/tiny-engineer-claude-code/src/play.js
index 6b16b3d4..d9abae43 100644
--- a/packages/tiny-engineer-claude-code/src/play.js
+++ b/packages/tiny-engineer-claude-code/src/play.js
@@ -16,7 +16,7 @@ export function parsePlayArgs(argv) {
 
     if (arg === "--name" || arg === "--url") {
       const value = argv[++i];
-      if (!value) return { error: `${arg} requires a value` };
+      if (!value || value.startsWith("-")) return { error: `${arg} requires a value` };
       opts[arg.slice(2)] = value;
       continue;
     }
diff --git a/packages/tiny-engineer-claude-code/test/play.test.js b/packages/tiny-engineer-claude-code/test/play.test.js
index 5618af6f..7cb4abba 100644
--- a/packages/tiny-engineer-claude-code/test/play.test.js
+++ b/packages/tiny-engineer-claude-code/test/play.test.js
@@ -14,6 +14,7 @@ test("play reads the WAV, animation name and URL", () => {
 test("play rejects bad arguments before contacting the robot", () => {
   assert.equal(parsePlayArgs(["--name", "talking"]).error, "play needs a WAV file");
   assert.equal(parsePlayArgs(["clip.wav", "--name"]).error, "--name requires a value");
+  assert.equal(parsePlayArgs(["clip.wav", "--name", "--url", "http://robot"]).error, "--name requires a value");
   assert.equal(parsePlayArgs(["a.wav", "b.wav"]).error, "Unknown argument: b.wav");
 });
 
diff --git a/skills/tiny-engineer-play/scripts/play b/skills/tiny-engineer-play/scripts/play
index 84155665..09e51e95 100755
--- a/skills/tiny-engineer-play/scripts/play
+++ b/skills/tiny-engineer-play/scripts/play
@@ -6,6 +6,12 @@ set -u
 clip=${1:?usage: play <clip.wav> [animation]}
 name=${2:-}
 url=${TINY_ENGINEER_URL:-http://tiny-engineer.local}
+
+# Only a bare animation name may reach the URL path ("../settings/reset" must not).
+case $name in
+  *[!a-z]*) echo "animation name must be lowercase letters, e.g. talking" >&2; exit 1 ;;
+esac
+
 url=${url%/}/play${name:+/$name}
 
 [ -r "$clip" ] || { echo "cannot read $clip" >&2; exit 1; }
diff --git a/src/animation/talking.cpp b/src/animation/talking.cpp
index cddad4ae..c7448751 100644
--- a/src/animation/talking.cpp
+++ b/src/animation/talking.cpp
@@ -59,13 +59,20 @@ void startTalking() {
 void updateTalking(uint32_t now) {
   updateAllServos();
 
-  if (hasPendingAnimation() && !g_poseFrozen) {
-    g_poseFrozen = true;
-    anim::parkForTransition();
+  if (hasPendingAnimation()) {
+    if (!g_poseFrozen) {
+      g_poseFrozen = true;
+      anim::parkForTransition();
+    }
+    return;
   }
 
   if (g_poseFrozen) {
-    return;
+    // The pending switch was cancelled (talking requested again): resume from here.
+    g_poseFrozen = false;
+    g_headPauseUntilMs = now;
+    g_neckNextMs = now;
+    g_gestureNextMs = now + randRangeMs(1500, 3500);
   }
 
   if (!servoAt(SERVO_HEAD).isMoving() && now >= g_headPauseUntilMs) {