elevenlabs-say: fix convert_realtime crash on default voice_settings (#341)

## Problem

`echo hi | nix run .#elevenlabs-say` crashed on the streaming path:

```
File ".../elevenlabs/realtime_tts.py", line 115, in convert_realtime
    voice_settings=voice_settings.dict() if voice_settings else None,
AttributeError: 'ellipsis' object has no attribute 'dict'
```

This is a bug in the `elevenlabs` SDK. `convert_realtime` defaults
`voice_settings` to its `OMIT` sentinel, which is the Ellipsis `...`.
The init-frame builder does `voice_settings.dict() if voice_settings
else None`, and `...` is truthy, so the default value calls `.dict()` on
the ellipsis and crashes. We did not pass `voice_settings`, so every
`--stream` invocation hit it.

## Fix

Pass `voice_settings=None` explicitly. `None` is falsy, so the SDK takes
the `else None` branch, and `None` already means "use the voice's stored
settings", so this is also the right value going forward, not just a
workaround.

## Tests

Added `test_stream_init_does_not_crash_on_omit_voice_settings`: it
monkeypatches the SDK's `connect` with a fake socket, drives
`stream_synthesize` far enough to build and send the init frame, and
asserts the frame carries a null `voice_settings`. This reproduces the
crash offline (it errors with the AttributeError if the explicit `None`
is removed), so the streaming path now has a no-network guard against
this class of SDK-integration break.

## Validation

- ✅ `nix build .#elevenlabs-say` (runs `ty`)
- ✅ `nix build .#elevenlabs-say.tests.streaming` and `.tests.printsHelp`
- ✅ `nix run .#lint`
- Not run against the live API: no `ELEVENLABS_API_KEY` here. This
clears the AttributeError that aborted streaming before any frame was
sent; confirm end to end with `echo hi | nix run .#elevenlabs-say`.

Filing the upstream bug at elevenlabs/elevenlabs-python separately.

---
Made with AI (Claude Opus 4.8).

Author: andrewgazelka

packages/elevenlabs-say/src/elevenlabs_say/__init__.py

@@ -274,11 +274,17 @@ def stream_synthesize(
     typed. It pins ``chunk_length_schedule=[50]`` for low latency, which is the
     intended trade for a pipe.
     """
+    # voice_settings must be passed explicitly as None. The SDK defaults it to its
+    # OMIT sentinel (the Ellipsis ...), then builds the init frame with
+    # `voice_settings.dict() if voice_settings else None`; Ellipsis is truthy, so
+    # the default crashes with AttributeError. None is falsy and means "use the
+    # voice's stored settings". https://github.com/elevenlabs/elevenlabs-python
     return stream_client(client).convert_realtime(
         voice_id=voice_id,
         text=text_source(args),
         model_id=args.model,
         output_format=args.output_format,
+        voice_settings=None,
     )
 
 

packages/elevenlabs-say/tests/test_streaming.py

@@ -6,13 +6,16 @@
 
 from __future__ import annotations
 
+import json
 import os
 import sys
 import tempfile
 import threading
 import time
 from pathlib import Path
 
+import elevenlabs.realtime_tts as realtime_module
+
 import elevenlabs_say as say
 
 
@@ -121,10 +124,61 @@ def isatty(self) -> bool:
         sys.stdin = original
 
 
+def test_stream_init_does_not_crash_on_omit_voice_settings() -> None:
+    """Regression: building convert_realtime's init frame must not trip the SDK's
+    OMIT-sentinel bug, where voice_settings defaults to Ellipsis (truthy, no
+    .dict()) and crashes. stream_synthesize passes voice_settings=None; assert the
+    init frame is sent and carries a null voice_settings.
+    """
+    os.environ["ELEVENLABS_API_KEY"] = "test-key-not-used"
+    client = say.make_client()
+
+    class _StopAfterInit(Exception):
+        pass
+
+    class FakeSocket:
+        def __init__(self) -> None:
+            self.sent: list[str] = []
+
+        def send(self, message: str) -> None:
+            self.sent.append(message)
+            raise _StopAfterInit
+
+        def recv(self, *args: object) -> str:
+            raise _StopAfterInit
+
+    socket = FakeSocket()
+
+    class FakeConnection:
+        def __enter__(self) -> FakeSocket:
+            return socket
+
+        def __exit__(self, *args: object) -> bool:
+            return False
+
+    original_connect = realtime_module.connect
+    realtime_module.connect = lambda *a, **k: FakeConnection()  # type: ignore[assignment]
+    try:
+        chunks = say.stream_synthesize(
+            client, say.parse_args(["hi", "--stream"]), "voice-id"
+        )
+        try:
+            next(iter(chunks))
+        except _StopAfterInit:
+            pass
+    finally:
+        realtime_module.connect = original_connect  # type: ignore[assignment]
+
+    assert socket.sent, "init frame was never sent"
+    init = json.loads(socket.sent[0])
+    assert init["voice_settings"] is None, init
+
+
 if __name__ == "__main__":
     test_stdin_yields_before_eof_and_rejoins_split_utf8()
     test_write_stream_writes_chunks_and_rejects_empty()
     test_play_stream_rejects_empty_without_spawning_ffplay()
     test_stream_client_narrows_to_realtime()
     test_should_stream_auto_and_overrides()
+    test_stream_init_does_not_crash_on_omit_voice_settings()
     print("elevenlabs-say streaming tests passed")