Weather Voice Assistant

Generated by Claude Code with Opus 4.5 - This entire project, including all source code and documentation, was created using Claude Code powered by Claude Opus 4.5.

A Claude Code skill that provides real-time weather information with voice input (speak your question) and voice output (hear the response). Built using the OpenAI Agents SDK with web search capabilities.

---

Table of Contents

1. What This Application Does
2. How It Works (Big Picture)
3. Important Limitations
4. Prerequisites
5. Installation Guide
6. Quick Start
7. Documentation Index
8. Troubleshooting
9. Getting Help

---

What This Application Does

The Weather Voice Assistant is a Claude Code skill that allows you to:

• Ask about weather using your voice - Speak into your microphone, and the app transcribes your question
• Get real-time weather data - Uses web search to find current, accurate weather information
• Hear the response spoken aloud - The weather report is read back to you using text-to-speech
• Or just use text - Type your question and read the response if you prefer

Example Interaction

You (speaking): "What's the weather in Tokyo?"
App (speaking): "In Tokyo, it's currently 52 degrees Fahrenheit with partly cloudy skies..."

---

How It Works (Big Picture)

┌─────────────────────────────────────────────────────────────────────────────┐
│                           WEATHER VOICE ASSISTANT                           │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│   STEP 1: INPUT                                                             │
│   ─────────────                                                             │
│   You can provide your question in three ways:                              │
│                                                                             │
│   [Microphone] ──► ffmpeg records ──► Whisper transcribes ──► Text query   │
│   [Audio File] ──► Whisper transcribes ──────────────────────► Text query   │
│   [Text Input] ──────────────────────────────────────────────► Text query   │
│                                                                             │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│   STEP 2: PROCESSING                                                        │
│   ──────────────────                                                        │
│                                                                             │
│   Text query ──► OpenAI Agent ──► Web Search ──► Weather Data               │
│                                                                             │
│   The AI agent understands your question and searches the web for           │
│   current weather information from reliable sources.                        │
│                                                                             │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│   STEP 3: OUTPUT                                                            │
│   ──────────────                                                            │
│                                                                             │
│   Weather Data ──► Agent formats response ──┬──► Text (always printed)     │
│                                             └──► TTS Audio (default)        │
│                                                                             │
│   By default, you'll see the weather printed AND hear it spoken.            │
│   Use --text-only flag to skip the audio.                                   │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

---

Important Limitations

Latency (Not Real-Time)

This application is NOT real-time. There is noticeable delay at each step:

Step	Typical Delay	Why
Recording	5-8 seconds	You need time to speak your question
Transcription	1-3 seconds	Audio is sent to OpenAI's Whisper API
Web Search	3-8 seconds	Agent searches the web for weather data
TTS Generation	2-4 seconds	Response is converted to speech
Audio Playback	5-15 seconds	The spoken response plays

Total time: 15-40 seconds from speaking to hearing the response.

This is a batch processing application, not a conversational assistant.

Other Limitations

• Requires active internet connection
• Requires valid OpenAI API key with credits
• Microphone input requires ffmpeg installed (Windows) or sox (macOS/Linux)
• Audio output requires working speakers/headphones

---

Prerequisites

Before installing, you need:

1. Windows 10/11, macOS, or Linux computer
2. Internet connection (required for all API calls)
3. OpenAI API account with credits (https://platform.openai.com)
4. Node.js 18 or higher (we'll show you how to install)
5. ffmpeg (Windows) or sox (macOS/Linux) for microphone input
6. Microphone (built-in laptop mic works fine)
7. Speakers or headphones for audio output

---

Installation Guide

Step 1: Install Node.js

Node.js is the runtime that executes this application.

Windows

1. Open PowerShell as Administrator (right-click PowerShell → Run as Administrator)
2. Run this command:

   winget install OpenJS.NodeJS.LTS
   

3. Close and reopen PowerShell
4. Verify installation:

   node --version
   

   You should see something like v20.x.x or v22.x.x

macOS

1. Open Terminal (Applications → Utilities → Terminal)
2. Install Homebrew if you don't have it:

   /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
   

3. Install Node.js:

   brew install node
   

4. Verify installation:

   node --version
   

Linux (Ubuntu/Debian)

1. Open Terminal
2. Run these commands:

   curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
   sudo apt-get install -y nodejs
   

3. Verify installation:

   node --version
   

---

Step 2: Install ffmpeg (Required for Microphone Input)

ffmpeg is the audio recording tool used on Windows.

Windows

1. Open PowerShell (regular, not as Administrator is fine)
2. Run this command:

   winget install ffmpeg
   

3. IMPORTANT: Close and reopen PowerShell for the PATH to update
4. Verify installation:

   ffmpeg -version
   

   You should see version information (e.g., ffmpeg version 7.x.x)

macOS

1. Open Terminal
2. Install sox (used instead of ffmpeg on macOS):

   brew install sox
   

3. Verify installation:

   sox --version
   

Linux (Ubuntu/Debian)

1. Open Terminal
2. Install alsa-utils (provides arecord):

   sudo apt install alsa-utils
   

3. Verify installation:

   arecord --version
   

---

Step 3: Get Your OpenAI API Key

1. Go to https://platform.openai.com/signup and create an account (or log in)
2. Add payment method at https://platform.openai.com/account/billing
3. Go to https://platform.openai.com/api-keys
4. Click "Create new secret key"
5. Give it a name like "Weather Voice Assistant"
6. Copy the key immediately - you won't be able to see it again!
7. The key looks like: sk-proj-abc123...xyz789

---

Step 4: Set Your API Key

Windows (PowerShell)

Temporary (current session only):

$env:OPENAI_API_KEY = "sk-proj-your-key-here"

Permanent (recommended):

1. Press Win + R, type sysdm.cpl, press Enter
2. Go to Advanced tab → Environment Variables
3. Under "User variables", click New
4. Variable name: OPENAI_API_KEY
5. Variable value: sk-proj-your-key-here
6. Click OK on all dialogs
7. Restart any open terminals

macOS / Linux

Temporary (current session only):

export OPENAI_API_KEY="sk-proj-your-key-here"

Permanent (recommended):

echo 'export OPENAI_API_KEY="sk-proj-your-key-here"' >> ~/.bashrc
source ~/.bashrc

---

Step 5: Install the Weather Voice Skill

1. Navigate to the skill directory:

   cd .claude/skills/weather-voice
   

2. Install dependencies:

   npm install
   

   This will download all required packages (takes 30-60 seconds).

3. Verify installation:

   npx tsx src/index.ts "Hello" --text-only
   

   You should see a response from the weather agent.

---

Quick Start

Basic Text Query

cd .claude/skills/weather-voice
npx tsx src/index.ts "What's the weather in New York?"

Text-Only (No Audio Output)

npx tsx src/index.ts "Weather in London" --text-only

Voice Input (Microphone)

npx tsx src/index.ts --mic --duration 6

Then speak your question when prompted!

Using with Claude Code

Important: In Claude Code CLI mode, you must type first to trigger voice input. You cannot simply speak into the microphone - Claude needs a typed message to know you want to use voice mode.

Step 1: Type a trigger phrase:

• "Let me speak my weather question"
• "I want to ask about weather using my microphone"
• "Use voice input for weather"

Step 2: Claude will start the recording and prompt you to speak.

Step 3: Speak your weather question when you see "Speak now!"

For text-only queries, simply type:

• "What's the weather in Paris?"
• "Weather in Tokyo, text only"

---

Documentation Index

Document	Description	Who It's For
README.md	Overview and installation (this file)	Everyone
QUICKSTART.md	10 example use cases	New users
USER_GUIDE.md	Complete user manual	All users
DEVELOPER.md	Technical deep-dive	Developers
CLAUDE.md	Claude Code integration	Claude Code users

---

Troubleshooting

"OPENAI_API_KEY not set"

You need to set your API key. See Step 4 above.

"ffmpeg not found"

Install ffmpeg and restart your terminal. See Step 2.

Microphone not recording audio

1. Check your microphone is set as default in Windows Sound Settings
2. Make sure microphone volume is up and not muted
3. Test in Windows Voice Recorder app first
4. See USER_GUIDE.md for detailed troubleshooting

Audio not playing

1. Check your speakers/headphones are connected
2. Check system volume is not muted
3. Try a different audio output device

---

Getting Help

1. Read the documentation - Most questions are answered in the guides
2. Check troubleshooting - Common issues and solutions
3. Claude Code issues - Report at https://github.com/anthropics/claude-code/issues

---

Credits

This project was entirely generated by Claude Code powered by Claude Opus 4.5 from Anthropic.

• Code generation: Claude Opus 4.5
• Documentation: Claude Opus 4.5
• Architecture design: Claude Opus 4.5

Technologies Used

• OpenAI Agents SDK - AI agent with web search capability
• OpenAI Whisper API - Speech-to-text transcription
• OpenAI TTS API - Text-to-speech synthesis
• ffmpeg - Audio recording (Windows)
• Node.js / TypeScript - Runtime and language

Reference Documentation

The following documentation sources were used as context for developing this skill:

Documentation	URL	Purpose
Claude Code Skills	https://code.claude.com/docs/en/skills	Skill definition format (SKILL.md)
OpenAI Agents SDK	https://openai.github.io/openai-agents-js/llms-full.txt	Agent creation, tools, web search
OpenAI Text-to-Speech	https://platform.openai.com/docs/guides/text-to-speech	TTS API usage, voice options

---

License

This is a Claude Code skill for personal/educational use.