Audio & Media

BotRS provides comprehensive support for audio and media content in QQ Guild bots. This includes voice channel management, live streaming capabilities, audio playback controls, and rich media message handling.

Overview

The audio and media system in BotRS consists of several key components:

• Audio Events: Real-time audio channel events (join/leave)
• Audio Controls: Playback management for audio content
• Voice Channels: Traditional voice chat functionality
• Live Channels: Streaming and broadcasting capabilities
• Media Messages: Rich content delivery (images, videos, files)

Audio Channel Events

Voice Channel Events

Handle users joining and leaving voice channels:

use botrs::{EventHandler, Context, PublicAudio, PublicAudioType};

impl EventHandler for MyBot {
    async fn audio_or_live_channel_member_enter(
        &self, 
        ctx: Context, 
        audio: PublicAudio
    ) {
        if let Some(channel_type) = audio.channel_type {
            match channel_type {
                PublicAudioType::Voice => {
                    println!("User joined voice channel: {:?}", audio.channel_id);
                }
                PublicAudioType::Live => {
                    println!("User joined live channel: {:?}", audio.channel_id);
                }
            }
        }
        
        // Welcome message for voice channel joins
        if let (Some(channel_id), Some(user_id)) = (&audio.channel_id, &audio.user_id) {
            let welcome_msg = format!("Welcome to the voice channel, <@{}>!", user_id);
            if let Err(e) = ctx.send_message(channel_id, &welcome_msg).await {
                eprintln!("Failed to send welcome message: {}", e);
            }
        }
    }
    
    async fn audio_or_live_channel_member_exit(
        &self, 
        ctx: Context, 
        audio: PublicAudio
    ) {
        println!("User left audio channel: {:?}", audio.user_id);
        
        // Optional: Send goodbye message
        if let (Some(channel_id), Some(user_id)) = (&audio.channel_id, &audio.user_id) {
            let goodbye_msg = format!("Goodbye, <@{}>!", user_id);
            let _ = ctx.send_message(channel_id, &goodbye_msg).await;
        }
    }
}

Audio Event Data

Access detailed information about audio events:

impl EventHandler for AudioBot {
    async fn audio_or_live_channel_member_enter(
        &self, 
        ctx: Context, 
        audio: PublicAudio
    ) {
        // Access audio event properties
        println!("Guild ID: {:?}", audio.guild_id);
        println!("Channel ID: {:?}", audio.channel_id);
        println!("User ID: {:?}", audio.user_id);
        println!("Channel Type: {:?}", audio.channel_type);
        
        // Get API client for additional operations
        let api = audio.api();
        
        // Perform additional operations if needed
        if let Some(guild_id) = &audio.guild_id {
            if let Some(user_id) = &audio.user_id {
                match api.guild_member(&ctx.token, guild_id, user_id).await {
                    Ok(member) => {
                        println!("Member {} joined audio channel", member.nick.unwrap_or_default());
                    }
                    Err(e) => {
                        eprintln!("Failed to get member info: {}", e);
                    }
                }
            }
        }
    }
}

Audio Controls

Audio Playback Management

Control audio playback in voice channels:

use botrs::{AudioControl, AudioStatus, Context};

impl MyBot {
    async fn handle_audio_command(&self, ctx: &Context, cmd: &str, channel_id: &str) {
        match cmd {
            "play" => {
                let audio_control = AudioControl {
                    audio_url: "https://example.com/audio.mp3".to_string(),
                    text: "Now playing: Example Song".to_string(),
                    status: AudioStatus::Start,
                };
                
                if let Err(e) = ctx.update_audio(channel_id, audio_control).await {
                    eprintln!("Failed to start audio: {}", e);
                }
            }
            "pause" => {
                let audio_control = AudioControl {
                    audio_url: String::new(),
                    text: "Audio paused".to_string(),
                    status: AudioStatus::Pause,
                };
                
                if let Err(e) = ctx.update_audio(channel_id, audio_control).await {
                    eprintln!("Failed to pause audio: {}", e);
                }
            }
            "resume" => {
                let audio_control = AudioControl {
                    audio_url: String::new(),
                    text: "Audio resumed".to_string(),
                    status: AudioStatus::Resume,
                };
                
                if let Err(e) = ctx.update_audio(channel_id, audio_control).await {
                    eprintln!("Failed to resume audio: {}", e);
                }
            }
            "stop" => {
                let audio_control = AudioControl {
                    audio_url: String::new(),
                    text: "Audio stopped".to_string(),
                    status: AudioStatus::Stop,
                };
                
                if let Err(e) = ctx.update_audio(channel_id, audio_control).await {
                    eprintln!("Failed to stop audio: {}", e);
                }
            }
            _ => {
                println!("Unknown audio command: {}", cmd);
            }
        }
    }
}

Audio Status Management

Track and respond to different audio states:

use botrs::AudioStatus;

impl MyBot {
    async fn handle_audio_status(&self, status: AudioStatus) {
        match status {
            AudioStatus::Start => {
                println!("Audio playback started");
                // Initialize audio session tracking
                self.start_audio_session().await;
            }
            AudioStatus::Pause => {
                println!("Audio playback paused");
                // Pause session tracking
                self.pause_audio_session().await;
            }
            AudioStatus::Resume => {
                println!("Audio playback resumed");
                // Resume session tracking
                self.resume_audio_session().await;
            }
            AudioStatus::Stop => {
                println!("Audio playback stopped");
                // Clean up audio session
                self.stop_audio_session().await;
            }
        }
    }
    
    async fn start_audio_session(&self) {
        // Implementation for starting audio session tracking
    }
    
    async fn pause_audio_session(&self) {
        // Implementation for pausing audio session
    }
    
    async fn resume_audio_session(&self) {
        // Implementation for resuming audio session
    }
    
    async fn stop_audio_session(&self) {
        // Implementation for stopping audio session
    }
}

Voice Channel Management

Microphone Controls

Manage microphone permissions and states:

impl EventHandler for VoiceBot {
    async fn message_create(&self, ctx: Context, msg: Message) {
        if let Some(content) = &msg.content {
            match content.as_str() {
                "!mute" => {
                    // Mute user's microphone
                    if let Some(author) = &msg.author {
                        if let Err(e) = ctx.off_microphone(&msg.channel_id, &author.id).await {
                            eprintln!("Failed to mute microphone: {}", e);
                        } else {
                            let _ = ctx.send_message(&msg.channel_id, "Microphone muted").await;
                        }
                    }
                }
                "!unmute" => {
                    // Unmute user's microphone
                    if let Some(author) = &msg.author {
                        if let Err(e) = ctx.on_microphone(&msg.channel_id, &author.id).await {
                            eprintln!("Failed to unmute microphone: {}", e);
                        } else {
                            let _ = ctx.send_message(&msg.channel_id, "Microphone unmuted").await;
                        }
                    }
                }
                "!mute_all" => {
                    // Mute all users in channel
                    if let Err(e) = ctx.mute_all(&msg.channel_id).await {
                        eprintln!("Failed to mute all: {}", e);
                    } else {
                        let _ = ctx.send_message(&msg.channel_id, "All users muted").await;
                    }
                }
                "!unmute_all" => {
                    // Unmute all users in channel
                    if let Err(e) = ctx.cancel_mute_all(&msg.channel_id).await {
                        eprintln!("Failed to unmute all: {}", e);
                    } else {
                        let _ = ctx.send_message(&msg.channel_id, "All users unmuted").await;
                    }
                }
                _ => {}
            }
        }
    }
}

Individual Member Control

Fine-grained control over individual members:

impl MyBot {
    async fn moderate_voice_channel(
        &self,
        ctx: &Context,
        channel_id: &str,
        user_id: &str,
        action: &str,
    ) -> Result<(), Box<dyn std::error::Error>> {
        match action {
            "mute" => {
                ctx.mute_member(channel_id, user_id, "Moderation action").await?;
                println!("Muted user {} in channel {}", user_id, channel_id);
            }
            "kick" => {
                // Note: kick_member is for guild-level, not voice-specific
                ctx.kick_member(channel_id, user_id, "Removed from voice channel").await?;
                println!("Kicked user {} from channel {}", user_id, channel_id);
            }
            _ => {
                println!("Unknown moderation action: {}", action);
            }
        }
        
        Ok(())
    }
}

Rich Media Messages

Image Messages

Send and handle image content:

use botrs::MessageParams;
use std::path::Path;

impl MyBot {
    async fn send_image(&self, ctx: &Context, channel_id: &str) -> Result<(), Box<dyn std::error::Error>> {
        // Method 1: Send local image file
        let image_path = Path::new("./images/example.png");
        let params = MessageParams::new_text("Check out this image!")
            .with_image_file(image_path)?;
        
        ctx.api.post_message_with_params(&ctx.token, channel_id, params).await?;
        
        // Method 2: Send image by URL
        let params = MessageParams::new_text("Image from URL")
            .with_image("https://example.com/image.png");
        
        ctx.api.post_message_with_params(&ctx.token, channel_id, params).await?;
        
        Ok(())
    }
}

Video Messages

Handle video content:

impl MyBot {
    async fn send_video(&self, ctx: &Context, channel_id: &str) -> Result<(), Box<dyn std::error::Error>> {
        // Send local video file
        let video_path = Path::new("./videos/example.mp4");
        let params = MessageParams::new_text("Here's a video!")
            .with_video_file(video_path)?;
        
        ctx.api.post_message_with_params(&ctx.token, channel_id, params).await?;
        
        Ok(())
    }
}

Audio Messages

Send audio content in messages:

impl MyBot {
    async fn send_audio_message(&self, ctx: &Context, channel_id: &str) -> Result<(), Box<dyn std::error::Error>> {
        // Send audio file
        let audio_path = Path::new("./audio/voice_message.mp3");
        let params = MessageParams::new_text("Voice message")
            .with_audio_file(audio_path)?;
        
        ctx.api.post_message_with_params(&ctx.token, channel_id, params).await?;
        
        Ok(())
    }
}

File Uploads

Handle general file uploads:

use botrs::FileType;

impl MyBot {
    async fn upload_file(&self, ctx: &Context, channel_id: &str, file_path: &Path) -> Result<(), Box<dyn std::error::Error>> {
        // Upload file and get file info
        let file_info = ctx.api.post_file(&ctx.token, file_path, FileType::Document).await?;
        
        // Send message with uploaded file
        let params = MessageParams::new_text("File uploaded successfully!")
            .with_file_url(&file_info.url);
        
        ctx.api.post_message_with_params(&ctx.token, channel_id, params).await?;
        
        Ok(())
    }
}

Advanced Audio Features

Audio Session Tracking

Track active audio sessions:

use std::collections::HashMap;
use std::sync::Arc;
use tokio::sync::Mutex;

pub struct AudioSessionManager {
    active_sessions: Arc<Mutex<HashMap<String, AudioSession>>>,
}

pub struct AudioSession {
    channel_id: String,
    start_time: std::time::Instant,
    current_track: Option<String>,
    status: AudioStatus,
}

impl AudioSessionManager {
    pub fn new() -> Self {
        Self {
            active_sessions: Arc::new(Mutex::new(HashMap::new())),
        }
    }
    
    pub async fn start_session(&self, channel_id: String, track_url: String) {
        let mut sessions = self.active_sessions.lock().await;
        let session = AudioSession {
            channel_id: channel_id.clone(),
            start_time: std::time::Instant::now(),
            current_track: Some(track_url),
            status: AudioStatus::Start,
        };
        sessions.insert(channel_id, session);
    }
    
    pub async fn update_session_status(&self, channel_id: &str, status: AudioStatus) {
        let mut sessions = self.active_sessions.lock().await;
        if let Some(session) = sessions.get_mut(channel_id) {
            session.status = status;
        }
    }
    
    pub async fn end_session(&self, channel_id: &str) {
        let mut sessions = self.active_sessions.lock().await;
        sessions.remove(channel_id);
    }
    
    pub async fn get_session_duration(&self, channel_id: &str) -> Option<std::time::Duration> {
        let sessions = self.active_sessions.lock().await;
        sessions.get(channel_id).map(|session| session.start_time.elapsed())
    }
}

Audio Bot Example

Complete example of an audio-enabled bot:

use botrs::{Client, EventHandler, Context, Message, PublicAudio, AudioControl, AudioStatus};

pub struct AudioBot {
    session_manager: AudioSessionManager,
}

impl AudioBot {
    pub fn new() -> Self {
        Self {
            session_manager: AudioSessionManager::new(),
        }
    }
}

impl EventHandler for AudioBot {
    async fn ready(&self, _ctx: Context, ready: Ready) {
        println!("Audio bot {} is ready!", ready.user.username);
    }
    
    async fn message_create(&self, ctx: Context, msg: Message) {
        if let Some(content) = &msg.content {
            if content.starts_with("!audio ") {
                let command = &content[7..];
                self.handle_audio_command(&ctx, &msg.channel_id, command).await;
            }
        }
    }
    
    async fn audio_or_live_channel_member_enter(&self, ctx: Context, audio: PublicAudio) {
        if let Some(user_id) = &audio.user_id {
            println!("User {} entered audio channel", user_id);
            
            // Send welcome audio message
            if let Some(channel_id) = &audio.channel_id {
                let welcome_audio = AudioControl {
                    audio_url: "https://example.com/welcome.mp3".to_string(),
                    text: "Welcome to the voice channel!".to_string(),
                    status: AudioStatus::Start,
                };
                
                let _ = ctx.update_audio(channel_id, welcome_audio).await;
            }
        }
    }
    
    async fn audio_or_live_channel_member_exit(&self, _ctx: Context, audio: PublicAudio) {
        if let Some(user_id) = &audio.user_id {
            println!("User {} left audio channel", user_id);
        }
    }
}

impl AudioBot {
    async fn handle_audio_command(&self, ctx: &Context, channel_id: &str, command: &str) {
        let parts: Vec<&str> = command.split_whitespace().collect();
        
        match parts.get(0) {
            Some(&"play") => {
                if let Some(&url) = parts.get(1) {
                    let audio_control = AudioControl {
                        audio_url: url.to_string(),
                        text: format!("Now playing: {}", url),
                        status: AudioStatus::Start,
                    };
                    
                    if let Ok(_) = ctx.update_audio(channel_id, audio_control).await {
                        self.session_manager.start_session(channel_id.to_string(), url.to_string()).await;
                        let _ = ctx.send_message(channel_id, "Audio playback started").await;
                    }
                }
            }
            Some(&"stop") => {
                let audio_control = AudioControl {
                    audio_url: String::new(),
                    text: "Playback stopped".to_string(),
                    status: AudioStatus::Stop,
                };
                
                if let Ok(_) = ctx.update_audio(channel_id, audio_control).await {
                    if let Some(duration) = self.session_manager.get_session_duration(channel_id).await {
                        let _ = ctx.send_message(
                            channel_id, 
                            &format!("Audio stopped. Duration: {:?}", duration)
                        ).await;
                    }
                    self.session_manager.end_session(channel_id).await;
                }
            }
            Some(&"pause") => {
                let audio_control = AudioControl {
                    audio_url: String::new(),
                    text: "Playback paused".to_string(),
                    status: AudioStatus::Pause,
                };
                
                if let Ok(_) = ctx.update_audio(channel_id, audio_control).await {
                    self.session_manager.update_session_status(channel_id, AudioStatus::Pause).await;
                    let _ = ctx.send_message(channel_id, "Audio paused").await;
                }
            }
            Some(&"resume") => {
                let audio_control = AudioControl {
                    audio_url: String::new(),
                    text: "Playback resumed".to_string(),
                    status: AudioStatus::Resume,
                };
                
                if let Ok(_) = ctx.update_audio(channel_id, audio_control).await {
                    self.session_manager.update_session_status(channel_id, AudioStatus::Resume).await;
                    let _ = ctx.send_message(channel_id, "Audio resumed").await;
                }
            }
            _ => {
                let _ = ctx.send_message(
                    channel_id, 
                    "Available commands: play <url>, stop, pause, resume"
                ).await;
            }
        }
    }
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let bot = AudioBot::new();
    
    let mut client = Client::new("your_app_id", bot)
        .intents(Intents::GUILD_MESSAGES | Intents::AUDIO_ACTION)
        .build()
        .await?;
    
    client.start().await?;
    Ok(())
}

Best Practices

Audio Performance

1. Use Appropriate Formats: Prefer MP3 or AAC for audio content
2. File Size Management: Keep audio files under reasonable size limits
3. URL Validation: Verify audio URLs are accessible before playback
4. Error Handling: Implement robust error handling for audio operations

Voice Channel Moderation

1. Permission Checks: Verify bot permissions before moderating
2. Audit Logging: Log moderation actions for accountability
3. Rate Limiting: Implement cooldowns for moderation commands
4. User Feedback: Provide clear feedback for moderation actions

Media Message Optimization

1. File Validation: Check file types and sizes before upload
2. Compression: Optimize images and videos for faster loading
3. Fallback Content: Provide text alternatives for media content
4. Cache Management: Consider caching frequently used media

The audio and media system in BotRS provides powerful capabilities for creating engaging, interactive voice experiences in QQ Guild communities. By leveraging these features effectively, you can build bots that enhance real-time communication and content sharing.