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.

What This Application Does
How It Works (Big Picture)
Important Limitations
Prerequisites
Installation Guide
Quick Start
Documentation Index
Troubleshooting
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:

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

Installation Guide

Step 1: Install Node.js

Node.js is the runtime that executes this application.

Windows

Open PowerShell as Administrator (right-click PowerShell → Run as Administrator)
Run this command:
```
winget install OpenJS.NodeJS.LTS
```
Close and reopen PowerShell
Verify installation:
```
node --version
```
You should see something like v20.x.x or v22.x.x

macOS

Open Terminal (Applications → Utilities → Terminal)

Install Homebrew if you don't have it:

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

Install Node.js:
```
brew install node
```
Verify installation:
```
node --version
```

Linux (Ubuntu/Debian)

Open Terminal

Run these commands:

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

Verify installation:
```
node --version
```

Step 2: Install ffmpeg (Required for Microphone Input)

ffmpeg is the audio recording tool used on Windows.

Windows

Open PowerShell (regular, not as Administrator is fine)
Run this command:
```
winget install ffmpeg
```
IMPORTANT: Close and reopen PowerShell for the PATH to update
Verify installation:
```
ffmpeg -version
```
You should see version information (e.g., ffmpeg version 7.x.x)

macOS

Open Terminal
Install sox (used instead of ffmpeg on macOS):
```
brew install sox
```
Verify installation:
```
sox --version
```

Linux (Ubuntu/Debian)

Open Terminal
Install alsa-utils (provides arecord):
```
sudo apt install alsa-utils
```
Verify installation:
```
arecord --version
```

Step 3: Get Your OpenAI API Key

Go to https://platform.openai.com/signup and create an account (or log in)
Add payment method at https://platform.openai.com/account/billing
Go to https://platform.openai.com/api-keys
Click "Create new secret key"
Give it a name like "Weather Voice Assistant"
Copy the key immediately - you won't be able to see it again!
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):

Press Win + R, type sysdm.cpl, press Enter
Go to Advanced tab → Environment Variables
Under "User variables", click New
Variable name: OPENAI_API_KEY
Variable value: sk-proj-your-key-here
Click OK on all dialogs
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

Navigate to the skill directory:
```
cd .claude/skills/weather-voice
```
Install dependencies:
```
npm install
```
This will download all required packages (takes 30-60 seconds).
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

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

Audio not playing

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

Getting Help

Read the documentation - Most questions are answered in the guides
Check troubleshooting - Common issues and solutions
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.

weather-voice

Weather Voice Assistant

Table of Contents

What This Application Does

Example Interaction

How It Works (Big Picture)

Important Limitations

Latency (Not Real-Time)

Other Limitations

Prerequisites

Installation Guide

Step 1: Install Node.js

Windows

macOS

Linux (Ubuntu/Debian)

Step 2: Install ffmpeg (Required for Microphone Input)

Windows

macOS

Linux (Ubuntu/Debian)

Step 3: Get Your OpenAI API Key

Step 4: Set Your API Key

Windows (PowerShell)

macOS / Linux

Step 5: Install the Weather Voice Skill

Quick Start

Basic Text Query

Text-Only (No Audio Output)

Voice Input (Microphone)

Using with Claude Code

Documentation Index

Troubleshooting

"OPENAI_API_KEY not set"

"ffmpeg not found"

Microphone not recording audio

Audio not playing

Getting Help

Credits

Technologies Used

Reference Documentation

License