# BillAI Bass Builder Guide

> Turn a Big Mouth Billy Bass animatronic fish into a real-time voice assistant using Strands BidiAgent, Amazon Nova 2 Sonic, and a Raspberry Pi 5.

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.

## Features
- Bidirectional real-time voice streaming via Strands BidiAgent
- Real-time lip-sync driven by RMS loudness in the audio playback callback
- Head, mouth, and tail motor control via MX1508 H-bridge and Raspberry Pi GPIO
- Amazon Nova 2 Sonic (amazon.nova-2-sonic-v1:0) on Amazon Bedrock
- Configurable personality via system prompt
- Standalone motors.py test rig for hardware verification
- Least-privilege IAM credential setup (one action, one model, one region)
- Optional X.509/AWS IoT Core production credential path
- asyncio-based concurrent body animation and audio streaming
- Step-by-step beginner-friendly build guide designed for AI-assisted construction

## Integrations
Amazon Bedrock, Amazon Nova 2 Sonic, Strands Agents (strands-agents[bidi,bidi-io]), AWS IAM, AWS IoT Core, Raspberry Pi 5, gpiozero, lgpio, PyAudio / PortAudio, ALSA

## Platforms
WINDOWS, MACOS, LINUX, API, CLI

## Pricing
Open Source

## Version
main

## Links
- Website: https://github.com/morganwilliscloud/billai-bass
- Documentation: https://github.com/morganwilliscloud/billai-bass/blob/main/README.md
- Repository: https://github.com/morganwilliscloud/billai-bass
- EveryDev.ai: https://www.everydev.ai/tools/billai-bass