player2py

Player2 Python Client

A Python client for the Player2 API - AI powered gaming tools.

Installation

pip install player2

Prerequisites

• Download and run the latest version of the Player2 App at https://player2.game
• Make sure the Player2 App is running and accessible at http://localhost:4315
• Ensure you are authenticated in the Player2 App

Quick Start

from player2 import Player2Client

# Initialize the client
client = Player2Client(game_name="my-awesome-game")

# Check if the server is healthy
health = client.health()
print(f"Player2 version: {health.client_version}")

# Get selected characters
characters = client.get_selected_characters()
for character in characters.characters:
    print(f"Character: {character.name} - {character.description}")

# Create a chat completion
response = client.chat_completions(
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Hello, how are you?"}
    ]
)
print(f"Response: {response.choices[0].message.content}")

# Text to speech
client.tts_speak(
    text="Hello, this is a test message!",
    voice_ids=["01955d76-ed5b-73e0-a88d-cbeb3c5b499d"],
    play_in_app=True
)

Features

• Characters API: Get selected characters from the Player2 App
• Chat API: Create chat completions following OpenAI API format
• Speech to Text (STT): Start/stop speech recognition and get recognized text
• Text to Speech (TTS): Convert text to speech with various voices
• System API: Health checks and system information

API Reference

Client Initialization

from player2 import Player2Client

client = Player2Client(
    base_url="http://localhost:4315",  # Default
    game_name="your-game-name",        # Required for tracking
    timeout=30                         # Request timeout in seconds
)

Characters API

# Get selected characters
characters = client.get_selected_characters()

Chat API

# Create chat completion
response = client.chat_completions(
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Hello!"}
    ]
)

Speech to Text (STT)

# Start speech recognition
client.stt_start(timeout=30)

# Stop speech recognition and get text
result = client.stt_stop()
print(f"Recognized text: {result.text}")

# Get available languages
languages = client.stt_languages()

# Get current language
current_lang = client.stt_get_language()

# Set language
client.stt_set_language(code="en-US")

Text to Speech (TTS)

# Get available voices
voices = client.tts_voices()

# Speak text
client.tts_speak(
    text="Hello, world!",
    voice_ids=["voice-id-1", "voice-id-2"],
    play_in_app=True,
    speed=1.0,
    voice_gender="female",
    voice_language="en_US",
    audio_format="mp3"
)

# Stop speaking
client.tts_stop()

# Get current volume
volume = client.tts_get_volume()

# Set volume (0.0 to 1.0)
client.tts_set_volume(volume=0.7)

System API

# Check health
health = client.health()
print(f"Client version: {health.client_version}")

Error Handling

The client raises specific exceptions for different error scenarios:

from player2 import Player2Error, Player2AuthError, Player2RateLimitError

try:
    response = client.chat_completions(messages=[...])
except Player2AuthError:
    print("Authentication required - please log in to Player2 App")
except Player2RateLimitError:
    print("Rate limit exceeded - please wait before making more requests")
except Player2Error as e:
    print(f"Player2 API error: {e}")

Examples

Simple Chat Bot

from player2 import Player2Client

client = Player2Client(game_name="chat-bot")

def chat_bot():
    while True:
        user_input = input("You: ")
        if user_input.lower() == "quit":
            break
            
        response = client.chat_completions(
            messages=[
                {"role": "system", "content": "You are a friendly chatbot."},
                {"role": "user", "content": user_input}
            ]
        )
        
        reply = response.choices[0].message.content
        print(f"Bot: {reply}")
        
        # Speak the response
        client.tts_speak(text=reply, play_in_app=True)

chat_bot()

Voice-Controlled Assistant

from player2 import Player2Client
import time

client = Player2Client(game_name="voice-assistant")

def voice_assistant():
    print("Voice assistant started. Say 'stop' to exit.")
    
    while True:
        # Start listening
        client.stt_start(timeout=10)
        print("Listening...")
        
        # Stop and get text
        try:
            result = client.stt_stop()
            text = result.text.lower()
            
            if "stop" in text:
                print("Goodbye!")
                break
                
            print(f"You said: {text}")
            
            # Get AI response
            response = client.chat_completions(
                messages=[
                    {"role": "system", "content": "You are a helpful voice assistant."},
                    {"role": "user", "content": text}
                ]
            )
            
            reply = response.choices[0].message.content
            print(f"Assistant: {reply}")
            
            # Speak response
            client.tts_speak(text=reply, play_in_app=True)
            
        except Exception as e:
            print(f"Error: {e}")

voice_assistant()

Contributing

• Fork the repository
• Create a feature branch
• Make your changes
• Add tests
• Submit a pull request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

• Join our Discord server for help and support
• Check the Player2 documentation for more information
• Report issues on GitHub

Developer Terms of Service

By using this API you agree to our Developer Terms of Service.