Skip to content

Commit f355789

Browse files
committed
add docs for games and stories
1 parent 7270224 commit f355789

File tree

6 files changed

+407
-9
lines changed

6 files changed

+407
-9
lines changed

Dockerfile.cpu

+1
Original file line numberDiff line numberDiff line change
@@ -46,6 +46,7 @@ COPY elevenlabs_voices.json.example /app/elevenlabs_voices.json.example
4646
COPY .env.sample /app/.env.sample
4747
COPY README.md /app/README.md
4848
COPY LICENSE /app/LICENSE
49+
COPY docs /app/docs
4950

5051
# Install Python dependencies (without cache to reduce image size)
5152
RUN pip install --upgrade pip && pip install --no-cache-dir -r /app/requirements.txt

README.md

+40-9
Original file line numberDiff line numberDiff line change
@@ -8,9 +8,11 @@ Voice Chat AI is a project that allows you to interact with different AI charact
88

99
You can run all locally, you can use openai for chat and voice, you can mix between the two. You can use ElevenLabs voices with ollama models all controlled from a Web UI. Ask the AI to look at your screen and it will explain in detail what it's looking at.
1010

11-
New - WebRTC Real Time API you can have a real time conversation, interrupt the AI and have instant responses. You can also use OpenAI's new TTS model gpt-4o-mini-tts to make the AI more human like with emotions and expressive voices.
11+
WebRTC Real Time API with OpenAI you can have a real time conversation, interrupt the AI and have instant responses. You can also use OpenAI's new TTS model gpt-4o-mini-tts to make the AI more human like with emotions and expressive voices.
1212

13-
New - Games you can play with AI as it guides you, New story mode to follow various story lines. Conversation history is saved to pick up where you left off later.
13+
Check out the game and story documentation:
14+
- [Games Documentation](docs/games.md): Play interactive games with various game master characters.
15+
- [Stories Documentation](docs/stories.md): Experience immersive story adventures with AI characters.
1416

1517
## Quick Start
1618

@@ -21,6 +23,7 @@ Get up and running fast with Voice Chat AI! 🔊
2123
- [**Configure Settings**](#configuration): Customize AI models, voices, and characters via `.env` on startup.
2224
- [**OpenAI Enhanced**](#openai-enhanced): Use OpenAI Enhanced Mode to speak with the AI in a more human like way with emotions.
2325
- [**OpenAI Realtime**](#openai-realtime): Experience real-time conversations with OpenAI's WebRTC-based Realtime API.
26+
- [**Game & Story Modes**](#game--story-modes): Explore interactive games and immersive storytelling experiences.
2427
- [**Add New Characters**](#adding-new-characters): Add new characters to the project.
2528
- [**Troubleshooting**](#troubleshooting): Fix common audio or CUDA errors.
2629

@@ -31,13 +34,12 @@ Get up and running fast with Voice Chat AI! 🔊
3134
- **Supports OpenAI, xAI or Ollama language models**: Choose the model that best fits your needs.
3235
- **Provides text-to-speech synthesis using XTTS or OpenAI TTS or ElevenLabs**: Enjoy natural and expressive voices.
3336
- **Provides speech to speech using OpenAI Realtime API**: Have a real time conversation with AI characters, interrupt the AI and have instant responses.
34-
- **NEW OpenAI Enhanced Mode TTS Model**: Uses emotions and prompts to make the AI more human like.
37+
- **OpenAI Enhanced Mode TTS Model**: Uses emotions and prompts to make the AI more human like.
3538
- **Flexible transcription options**: Uses OpenAI transcription by default, with option to use Local Faster Whisper.
36-
- **No typing needed, just speak**: Hands-free interaction makes conversations smooth and effortless.
3739
- **Analyzes user mood and adjusts AI responses accordingly**: Get personalized responses based on your mood from sentiment analysis.
38-
- **Easy configuration through environment variables**: Customize the application to suit your preferences with minimal effort.
39-
- **WebUI or Terminal usage**: Run with your preferred method , but recommend the ui as you can change characters, model providers, speech providers, voices, ect..
40+
- **WebUI or Terminal usage**: Run with your preferred method , but recommend the ui as you can change characters, model providers, speech providers, voices, ect. on the fly.
4041
- **HUGE selection of built in Characters**: Talk with the funniest and most insane AI characters! Play escape room games, follow story lines, and more.
42+
- **Interactive Games & Stories**: Enjoy 15+ different game types (word puzzles, trivia, escape rooms) and interactive storytelling adventures.
4143
- **Docker Support**: Prebuilt image from dockerhub or build yor own image with or without nvidia cuda. Can run on CPU only.
4244

4345
https://github.com/user-attachments/assets/f4401acf-4422-458f-bcbc-06ff63de010e
@@ -48,7 +50,7 @@ https://github.com/user-attachments/assets/f4401acf-4422-458f-bcbc-06ff63de010e
4850

4951
- Python 3.10
5052
- ffmpeg
51-
- Ollama models or Openai API or xAI for chat
53+
- Ollama models or OpenAI or xAI for chat
5254
- Local XTTS or Openai API or ElevenLabs API for speech
5355
- Microsoft C++ Build Tools on windows
5456
- Microphone
@@ -177,8 +179,6 @@ docker-compose up -d
177179

178180
### 🐳 Docker run
179181

180-
### without Nvidia Cuda - cpu mode
181-
182182
Cuda and cudnn not supported. No gpu is used and slower when using local xtts and faster-whisper. If only using Openai or Elevenlabs for voices is perfect. Still works with xtts but slower. First run it downloads faster whisper model 1gb for transcription.
183183

184184
> Remove the elevenlabs_voices.json volume mount if not using ElevenLabs.
@@ -523,6 +523,32 @@ https://github.com/user-attachments/assets/d1cc9ca4-e750-4c36-816e-6f27b8caeec1
523523
3. Click "Start Session" to establish the connection
524524
4. Click the microphone button and start speaking naturally
525525
526+
## Game & Story Modes
527+
528+
Interactive gameplay and storytelling experiences that transform your AI conversations into structured, immersive adventures.
529+
530+
### Game Characters
531+
532+
The application includes over 15 different game types where AI characters act as game masters, guiding you through various challenges:
533+
534+
- **Word Games**: Hangman, Word Weaver, Alphabet Race, Silly Sentences
535+
- **Trivia & Puzzles**: Movie Quotes, Animal Facts, History Mystery, What's My Job
536+
- **Logic & Creativity**: Jester's Truth, Escape Master, Opposite Master, Guess Gibberish
537+
538+
[View full games documentation](docs/games.md) for detailed descriptions of all available games.
539+
540+
### Story Adventures
541+
542+
Enjoy immersive storytelling experiences with AI-driven narratives across various settings:
543+
544+
- **Noir Detective**: Solve mysteries in a gritty urban landscape
545+
- **Space Station**: Navigate challenges on an interstellar vessel
546+
- **Oregon Trail**: Experience frontier survival adventures
547+
- **Wilderness**: Explore untamed natural environments
548+
- **Haunted Mansion**: Brave supernatural challenges in a spooky setting
549+
550+
[View full stories documentation](docs/stories.md) for all available story adventures.
551+
526552
## Adding New Characters
527553
528554
1. Create a new folder for the character in the project's characters directory, (e.g. `character/wizard`).
@@ -571,6 +597,9 @@ This is for sentiment analysis, based on what you say, you can guide the AI to r
571597
572598
## Troubleshooting
573599
600+
<details>
601+
<summary>Click to expand</summary>
602+
574603
### Could not locate cudnn_ops64_9.dll or Unable to load any of libcudnn_ops.so.9.1.0
575604
576605
```bash
@@ -656,6 +685,8 @@ To fix this issue:
656685
657686
If you continue to have issues after these steps, creating a fresh virtual environment and reinstalling all dependencies is the most reliable solution.
658687
688+
</details>
689+
659690
## Watch the Demos
660691
661692
OpenAI RealTime

app/static/images/games.png

2.83 MB
Loading

app/static/images/oregon.jpg

88.6 KB
Loading

docs/games.md

+249
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,249 @@
1+
# Interactive Games Collection
2+
3+
![games](../app/static/images/games.png)
4+
5+
## About Game Characters
6+
7+
Game characters provide engaging, rule-based interactive experiences that transform your conversation into structured gameplay. Each character serves as a game master or host, guiding you through unique challenges, puzzles, or word games with clear objectives and feedback.
8+
9+
For the best experience, it's recommended to use **GPT-4o** or similar advanced models, as they can better track game states, remember complex rules, and maintain consistency throughout gameplay.
10+
11+
## How Game Characters Work
12+
13+
All game characters follow a consistent structure:
14+
15+
1. **Clear Rules Introduction**: Your first interaction explains the game concept, rules, and victory conditions.
16+
17+
2. **Turn-Based Gameplay**: Most games feature alternating turns between you and the AI, creating a structured play experience.
18+
19+
3. **Score or Progress Tracking**: The AI keeps track of your progress, points, or game state throughout the session.
20+
21+
4. **Adaptive Difficulty**: Many games can adjust to your skill level, becoming more challenging as you improve.
22+
23+
5. **Multiple Rounds**: Games are designed to be played multiple times with new content each time.
24+
25+
6. **Helpful Guidance**: If you get stuck, the AI can provide hints or assistance appropriate to the game.
26+
27+
7. **Victory and Defeat Conditions**: Games have clear outcomes that determine success or failure.
28+
29+
## Available Games
30+
31+
### Hangman (game_hangman)
32+
33+
**Concept**: A darkly theatrical version of the classic word-guessing game
34+
35+
**Role**: You must guess a hidden word one letter at a time before the gallows are completed
36+
37+
**Key Features**:
38+
- Dramatic narrative as the gallows are constructed with each wrong guess
39+
- Diverse word categories and difficulty levels
40+
- Track of guessed letters and remaining attempts
41+
- Macabre but playful atmosphere with vivid descriptions
42+
- Score tracking across multiple games
43+
44+
### Werewolf (game_werewolf)
45+
46+
**Concept**: A virtual version of the social deduction game where one villager is secretly a werewolf
47+
48+
**Role**: Detective trying to identify the werewolf before all villagers are eliminated
49+
50+
**Key Features**:
51+
- Five distinct virtual villagers with unique personalities and backgrounds
52+
- Day/night cycle with murders occurring at night
53+
- Accusation system requiring deduction and careful observation
54+
- Environmental clues and suspicious behaviors to analyze
55+
- Atmospheric storytelling with a horror theme
56+
57+
### Word Weaver (game_word_weaver)
58+
59+
**Concept**: A word chain game where each word must begin with the last letter of the previous word
60+
61+
**Role**: Co-creator of a 10-word chain that becomes a mini-story
62+
63+
**Key Features**:
64+
- Alternating turns adding words to the chain
65+
- Strict rule enforcement for letter connections
66+
- A complete 10-word story created from your chain
67+
- Creative storytelling that incorporates all words in sequence
68+
- Multiple rounds with different starting words
69+
70+
### Jester's Truth (game_jesters_truth)
71+
72+
**Concept**: A peculiar version of "Two Truths and a Lie" with bizarre, outlandish statements
73+
74+
**Role**: Challenger trying to identify which of the Jester's three wild statements is false
75+
76+
**Key Features**:
77+
- Incredibly bizarre yet true statements mixed with plausible lies
78+
- Score tracking across multiple rounds
79+
- Increasingly challenging statements as the game progresses
80+
- Theatrical reveals with explanations of the truths and lies
81+
- Diverse categories of absurd statements for variety
82+
83+
### Escape Master (game_escape_master)
84+
85+
**Concept**: Virtual escape room with puzzles, hidden objects, and codes to decipher
86+
87+
**Role**: Trapped visitor trying to solve puzzles to escape the room
88+
89+
**Key Features**:
90+
- Detailed environment with interactive objects and hidden clues
91+
- Logical puzzle sequences requiring observation and deduction
92+
- Easy and hard modes affecting puzzle complexity and hint frequency
93+
- Inventory system tracking collected items
94+
- Multiple escape room themes with different puzzles
95+
96+
### Movie Quotes (game_movie_quotes)
97+
98+
**Concept**: Movie quote guessing game testing your film knowledge
99+
100+
**Role**: Contestant trying to identify films from their famous quotes
101+
102+
**Key Features**:
103+
- Diverse selection of movie quotes from different eras and genres
104+
- Multiple difficulty levels affecting quote obscurity
105+
- Hint system providing additional context when needed
106+
- Score tracking across rounds
107+
- Educational content about film history and trivia
108+
109+
### Alphabet Race (game_alphabet_race)
110+
111+
**Concept**: Fast-paced word generation game based on categories and letters
112+
113+
**Role**: Competitor racing to find words in specific categories starting with given letters
114+
115+
**Key Features**:
116+
- Various categories (animals, foods, countries, etc.)
117+
- Progressive difficulty as you advance through the alphabet
118+
- Timed challenges adding pressure to each round
119+
- Score tracking based on speed and word appropriateness
120+
- Special bonus rounds with more challenging letter combinations
121+
122+
### Villain Confessor (game_villain_confessor)
123+
124+
**Concept**: Interrogation game where you question fictional villains to uncover their crimes
125+
126+
**Role**: Detective interviewing notorious but mysterious criminals
127+
128+
**Key Features**:
129+
- Unique villains with distinct personalities and hidden secrets
130+
- Question-based gameplay requiring strategic interrogation
131+
- Clue system revealing pieces of the crime puzzle
132+
- Time pressure increasing tension
133+
- Victory when you correctly identify the villain's specific crime
134+
135+
### Door Master (game_door_master)
136+
137+
**Concept**: Choose-your-adventure game with doors leading to different scenarios
138+
139+
**Role**: Explorer navigating through a series of mysterious doors
140+
141+
**Key Features**:
142+
- Each door leads to unique environments with different challenges
143+
- Decision-based gameplay affecting subsequent door options
144+
- Resource management between doors (keys, items, health)
145+
- Multiple possible paths through the game
146+
- Various endings depending on your door choices
147+
148+
### Animal Facts
149+
150+
**Concept**: Educational quiz game challenging players to identify animals from unusual facts.
151+
152+
**Role**: The Animal Expert presents fascinating facts about creatures and evaluates guesses.
153+
154+
**Key Features**:
155+
- Diverse animal selection from various habitats
156+
- Three difficulty levels
157+
- Educational content focusing on unique animal adaptations and behaviors
158+
159+
### History Mystery
160+
161+
**Concept**: Historical figure identification game based on achievements and impact.
162+
163+
**Role**: The History Detective presents clues about influential historical figures for players to identify.
164+
165+
**Key Features**:
166+
- Diverse historical figures from various fields and time periods
167+
- Progressive hint system
168+
- Educational content highlighting significant historical contributions
169+
170+
### Guess Gibberish
171+
172+
**Concept**: Word puzzle game where players decode nonsensical phrases that sound like familiar expressions.
173+
174+
**Role**: The Gibberish Guru presents phonetic puzzles that players must translate into common phrases.
175+
176+
**Key Features**:
177+
- Three difficulty levels of increasingly complex gibberish phrases
178+
- Hint system for struggling players
179+
- Playful presentation of linguistic puzzles
180+
181+
### Mix-Up Market
182+
183+
**Concept**: Word unscrambling game set in a peculiar shop where all merchandise names are jumbled.
184+
185+
**Role**: The Shopkeeper presents scrambled item names with cryptic descriptions for players to decipher.
186+
187+
**Key Features**:
188+
- Progressive clue system
189+
- Varied item categories
190+
- Five-round structure with increasing difficulty
191+
- Theatrical shop-themed presentation
192+
193+
### Silly Sentences
194+
195+
**Concept**: Creative completion game challenging players to finish sentence starters in imaginative ways.
196+
197+
**Role**: The Sentence Sage provides open-ended beginnings that invite clever, amusing, or unexpected completions.
198+
199+
**Key Features**:
200+
- Diverse starter categories (personification, absurd situations, fantastical elements)
201+
- Specific feedback on creativity
202+
- Encouraging atmosphere for imaginative thinking
203+
204+
### What's My Job?
205+
206+
**Concept**: Occupation-guessing game based on progressively revealing clues about various professions.
207+
208+
**Role**: The Career Cryptic provides three clues per job that progress from vague to specific.
209+
210+
**Key Features**:
211+
- Diverse occupation selection
212+
- Structured three-clue format
213+
- Five-round gameplay with increasing difficulty
214+
- Gameshow-style presentation
215+
216+
### Opposite Master
217+
218+
**Concept**: Mental agility game challenging players to quickly provide opposites to given words or concepts.
219+
220+
**Role**: The Opposite Master presents a series of words and evaluates the speed and accuracy of opposite responses.
221+
222+
**Key Features**:
223+
- Progressive difficulty from simple physical opposites to abstract concepts
224+
- Rapid-fire gameplay format
225+
- Scoring based on speed and accuracy
226+
- Energetic competitive atmosphere
227+
228+
## Creating Your Game Experience
229+
230+
When using game characters:
231+
232+
1. **Understand the Rules**: Pay attention to the initial explanation to understand how to play.
233+
2. **Focus on One Game at a Time**: Complete rounds of a single game before switching to another.
234+
3. **Be Specific**: Clear, direct responses work best for game mechanics.
235+
4. **Ask for Help**: If you're confused about rules or stuck, ask for clarification.
236+
5. **Explore Variations**: Many games offer different modes or difficulty levels to try.
237+
238+
## Tips for the Best Experience
239+
240+
- Start with simpler games like Hangman or Word Weaver before trying complex ones like Escape Master.
241+
- For word games, use common English words unless otherwise specified.
242+
- In deduction games like Werewolf, take notes on clues and behaviors.
243+
- For puzzle games like Escape Master, be thorough in your exploration and examination.
244+
- For best results, use GPT-4o or another advanced model with strong reasoning capabilities.
245+
- Be patient with complex games - some require multiple turns to fully understand.
246+
247+
---
248+
249+
*More games will be added to this collection over time. Each offers unique challenges and gameplay experiences to enjoy.*

0 commit comments

Comments
 (0)