BillAI Bass Builder Guide

BillAI Bass Builder Guide is an open-source hardware/software project that transforms a Big Mouth Billy Bass novelty toy into a fully functional voice assistant. The fish runs a Strands Agents bidirectional streaming agent (BidiAgent) on a Raspberry Pi 5, streaming live audio to and from Amazon Nova 2 Sonic on Amazon Bedrock — head swiveling, mouth lip-syncing, and tail flapping in real time. The project was created with help from Claude Code and is explicitly designed to be built alongside an AI assistant.

What It Is

BillAI Bass is a step-by-step DIY guide and accompanying Python codebase for converting a commercially available Big Mouth Billy Bass (the modern "Gemmy" version with two motors) into a conversational AI device. The core software uses Strands Agents' experimental BidiAgent and BidiAudioIO APIs to establish a bidirectional audio stream with Amazon Nova 2 Sonic (amazon.nova-2-sonic-v1:0) on Amazon Bedrock. The project targets complete beginners — the README notes the original builder had never plugged in a Raspberry Pi before and completed the build in a weekend.

How the Lip-Sync Architecture Works

The key technical insight is that Nova Sonic delivers audio much faster than it plays back, so naive "flap when data arrives" approaches fail. Instead, the project subclasses Strands' internal _BidiAudioOutput class (BillyBody) and measures RMS loudness inside the audio playback callback — the exact bytes hitting the speaker at that moment — then drives the mouth PWM motor from that real-time level. Head position is governed by an audio-silence timer (SILENCE = 1.5 seconds), and tail flaps are triggered on loudness peaks above a configurable EMPHASIS threshold with a rate-limiting cooldown. All three behaviors run concurrently via asyncio.gather.

Hardware and Setup Path

The build requires roughly $240 in components (January 2026 prices per the README), including:

• Big Mouth Billy Bass (modern Gemmy version, ~$30)
• Raspberry Pi 5 8GB with Active Cooler (~$90 combined)
• MX1508 dual H-bridge motor driver (~$9 for a 5-pack)
• USB mini speaker and USB gooseneck microphone (~$28 combined)
• Soldering iron kit, DuPont jumper wires, and flush cutters

The guide walks through flashing Raspberry Pi OS Lite (64-bit, Python 3.12+ required), ALSA audio configuration using card names rather than numbers, Python venv setup with strands-agents[bidi,bidi-io] and gpiozero, and AWS IAM credential scoping. A standalone motors.py test rig is included to verify wiring before running the full agent.

Security Model

The README emphasizes least-privilege AWS credentials throughout. The recommended setup creates a dedicated billy-bass IAM user with a single inline policy allowing only bedrock:InvokeModelWithBidirectionalStream on the specific Nova Sonic model ARN in us-east-1 — no S3, no EC2, no other Bedrock models. The repo also includes an optional iot-identity/ folder with a CloudFormation template and walkthrough for upgrading to X.509 certificate-based authentication via AWS IoT Core's credential provider, eliminating long-lived secrets from the device entirely.

Current Status and Adoption Signal

The repository was created on June 16, 2026 and last updated July 15, 2026, indicating active recent development. It has accumulated 55 stars and 3 forks since launch. The project explicitly pins to Strands Agents' experimental bidi API and warns users to record their installed version, as the API subclasses a private class that may change in future releases. The README notes that Nova Sonic v1 hits end-of-life in September 2026 and directs users to amazon.nova-2-sonic-v1:0 (Nova 2 Sonic). The project cites inspiration from the earlier billy-b-assistant project but is rebuilt entirely on the Strands framework.