Bedtime Stories App (Amazon Nova + LiveKit)

This project is a speech-first bedtime companion for kids. It includes:

• A Python LiveKit Agent worker with Amazon Nova realtime
• A pnpm-based Next.js frontend using shadcn and LiveKit Agents UI components
• An Android-ready token endpoint for joining LiveKit rooms

1. What You Get In This Repo

• Voice agent worker in main.py that can:
  • tell calm bedtime stories
  • hold meaningful child-friendly conversation
  • sing original lullaby-style songs on request
• Android token API in token_api.py:
  • POST /api/token/android
  • returns room, participant identity, and JWT token
• Web app in web/app/page.tsx using generated LiveKit Agents UI components

2. Prerequisites

• Python 3.12+
• A running LiveKit server (Cloud or self-hosted)
• AWS account access to Amazon Nova Realtime
• Node.js 20+ (for web app)
• Android Studio (for Android app)

3. Configure Environment

Use your existing .env and ensure it contains:

• LIVEKIT_URL
• LIVEKIT_API_KEY
• LIVEKIT_API_SECRET

For AWS, this project works with your existing aws configure sso session.

4. Run The Voice Agent Worker

Install dependencies:

pip install -e .

Run the worker:

python main.py dev

If your installed LiveKit CLI entrypoints differ, use:

python main.py

5. Run The Android Token API

Install backend dependencies:

pip install -e .

Run API server:

uvicorn token_api:app --host 0.0.0.0 --port 8000 --reload

Endpoint for Android:

• POST http://localhost:8000/api/token/android

Sample request:

{
  "participant_name": "Kid Listener",
  "room_name": "bedtime-room"
}

6. Web App (pnpm + shadcn + LiveKit Agents UI)

The web app is already scaffolded in web and uses pnpm.

Install and run:

cd web
pnpm install
pnpm dev

Optional environment variables for the web app:

• BACKEND_TOKEN_ENDPOINT (default: http://127.0.0.1:8000/api/token/android)
• NEXT_PUBLIC_TOKEN_ENDPOINT (default: /api/token)

The web app token proxy route is in web/app/api/token/route.ts.

7. Android App (LiveKit + Compose UI)

In Android app dependencies, add LiveKit Android SDK and Compose tooling.

Recommended architecture:

• BedtimeViewModel: fetch token + room details from your backend
• LiveKitService: manages room connection
• Compose screen with:
  • Push-to-talk or always-on mic mode
  • Speaking indicator animation
  • Story mood selector chips

Android flow

1. App requests a token from your backend.
2. App joins LiveKit room with child participant.
3. Python agent worker joins same room and speaks with the child.
4. Audio is streamed bidirectionally in realtime.

8. Child Safety + Product Guardrails

• Keep prompts and outputs age-appropriate.
• Never allow unsafe content categories.
• Log sessions for moderation with privacy controls.
• Add parent dashboard controls:
  • session length cap
  • topic allowlist/blocklist
  • bedtime schedule windows

9. Suggested Next Build Steps

1. Add authentication and parent identity checks to POST /api/token/android.
2. Add parent controls for max session duration and content filters.
3. Build Android Compose screen with room join and voice visualizer.
4. Add moderation logs and sentiment analytics for session safety.

10. Troubleshooting

• If agent joins but does not respond:
  • verify AWS credentials and region
  • confirm Nova realtime access is enabled
  • ensure room audio track is subscribed
• If web/Android cannot connect:
  • verify token expiry and participant identity
  • confirm LIVEKIT_URL uses wss://
  • confirm firewall/network allows websocket traffic