Installation

System Requirements

• Python 3.10 or higher

• Windows, macOS, or Linux

• At least 2GB of available RAM

• Internet connection for streaming service integrations

• OBS Studio (for browser source integration)

Installing from Source

1. Clone the repository:

   git clone https://github.com/yourusername/mycelian.git
   cd mycelian
   

2. Install using UV (recommended):

   uv pip install -e .
   

   Or using pip:

   pip install -e .
   

3. Install development dependencies (optional):

   uv pip install -e ".[docs]"
   

First Launch

Desktop Application Interface

1. Launch Mycelian:

   python main.py
   

2. The desktop application will open with a tabbed interface including: * Activity Feed: Real-time alert monitoring and history * Settings: Service configuration and database setup * Custom Sources: Template configuration management * Source Controls: Interactive template controls * Connectors: Automation workflow designer and management

3. The Flask web server will automatically start on http://localhost:5000 to serve browser sources

Initial Configuration

Database Setup

On first launch, configure your database in the Settings tab:

Option 1: Firebase Realtime Database (Recommended for cloud sync)

1. Create a Firebase project at https://console.firebase.google.com/

2. Enable Realtime Database

3. Download your service account key file

4. In Settings → Database Configuration: * Select “Firebase” as database type * Browse and select your Firebase key file * Enter your database URL * Test the connection

Option 2: Local SQLite Database

1. In Settings → Database Configuration: * Select “SQLite” as database type * Choose or create a local database file * Test the connection

The application will create necessary database structures automatically.

Service Integration Setup

🔑 IMPORTANT - Personal Credentials Required:

Each service integration requires you to create your own developer applications and obtain your own unique credentials. Mycelian does not provide shared API keys or credentials. You must:

• Create developer accounts with each service you want to use

• Register your own applications on their developer platforms

• Generate your own Client IDs and Client Secrets

• Use your own account credentials for OAuth authorization

This ensures your data privacy and complies with each service’s terms of use.

Twitch Integration

Prerequisites: * Active Twitch account * Twitch Developer account

⚠️ Important: You MUST create your own Twitch application to get unique credentials

Setup Process:

1. Create Your Own Twitch Application: * Visit https://dev.twitch.tv/console/apps * Log in with your Twitch account * Click “Register Your Application” * Fill in application details:

   • Name: “Mycelian” (or your preferred name)

   • OAuth Redirect URI: http://localhost:3000

   • Category: “Application Integration”

   • Click “Create”

2. Get Your Unique Credentials: * Click “Manage” on your newly created application * Copy your Client ID (visible immediately) * Click “New Secret” to generate your Client Secret * Copy your Client Secret (keep this secure!)

3. Configure Mycelian: * In Mycelian Settings → Service Integrations → Twitch: * Enter YOUR unique Client ID and Client Secret * Click “Connect to Twitch” * Complete OAuth authorization in your browser * Verify connection status shows “Connected”

Features Enabled: * Real-time follower and subscription alerts * Chat integration with emotes and badges * Channel point redemption notifications * Raid and host alerts * Bits/cheer tracking

Spotify Integration

Prerequisites: * Spotify Premium account (for full playback control) * Spotify Developer account

⚠️ Important: You MUST create your own Spotify application to get unique credentials

Setup Process:

1. Create Your Own Spotify Application: * Visit https://developer.spotify.com/dashboard * Log in with your Spotify account * Click “Create app” * Fill in application details:

   • App name: “Mycelian” (or your preferred name)

   • App description: “Stream overlay integration”

   • Website: Leave blank or add your stream URL

   • Redirect URI: http://localhost:8888/callback

   • Which API/SDKs are you planning to use: “Web API”

   • Accept terms and click “Save”

2. Get Your Unique Credentials: * Click on your newly created application * Go to “Settings” * Copy your Client ID (visible immediately) * Click “View client secret” to reveal your Client Secret * Copy your Client Secret (keep this secure!)

3. Configure Mycelian: * In Mycelian Settings → Service Integrations → Spotify: * Enter YOUR unique Client ID and Client Secret * Click “Connect to Spotify” * Authorize the application in your browser * Verify connection status shows “Connected”

Features Enabled: * Now playing track display * Album artwork integration * Playback history tracking * Track information for overlays

YouTube Integration

Prerequisites: * Google account (Gmail) * YouTube channel(s) you want to monitor * Basic understanding of API concepts

⚠️ Important: You MUST create your own Google Cloud project and API key

Setup Process:

1. Create a Google Cloud Project:

   • Visit https://console.cloud.google.com/

   • Sign in with your Google account (Gmail)

   • Click “Create Project” (or select an existing project if you have one)

   • Enter a project name: “Mycelian YouTube Integration” (or your preferred name)

   • Choose your organization if applicable

   • Click “Create”

2. Enable the YouTube Data API v3:

   • In your Google Cloud Console, go to “APIs & Services” → “Library”

   • Search for “YouTube Data API v3”

   • Click on “YouTube Data API v3” from the results

   • Click “Enable” to activate the API for your project

3. Create API Credentials:

   • Go to “APIs & Services” → “Credentials”

   • Click “Create Credentials” → “API key”

   • Your API key will be generated and displayed

   • IMPORTANT: Copy and save your API key immediately (you won’t be able to see it again)

   • SECURITY NOTE: Keep your API key secure and never share it publicly

4. Configure API Key Restrictions (Recommended):

   • Click on your newly created API key

   • Under “API restrictions”: - Select “Restrict key” - Check “YouTube Data API v3”

   • Under “Application restrictions”: - Select “HTTP referrers (web sites)” - Add referrer: localhost:* (for local development) - You can add additional restrictions based on your needs

   • Click “Save” to apply the restrictions

5. Configure Mycelian:

   • Launch Mycelian and go to Settings → YouTube Integration tab

   • Enter your API key in the “API Key” field

   • Enter channel URLs separated by pipe symbols (|): https://youtube.com/@Channel1|https://youtube.com/@Channel2

   • Supported URL formats: - https://youtube.com/@ChannelHandle - https://youtube.com/channel/UC_CHANNEL_ID - https://youtube.com/c/CustomChannelName - https://youtube.com/user/Username

   • Click “Save Settings”

   • Test the connection to verify everything works

API Quota and Costs:

• Free Tier: YouTube Data API v3 provides 10,000 units per day for free

• Cost: $0.50 per 1,000 units beyond the free tier

• Usage: Each video/channel lookup uses approximately 1-3 units

• Monitoring: With 5-minute refresh intervals, typical usage is well within free limits

Security Best Practices:

• API Key Restrictions: Always restrict your API key to specific APIs and referrers

• Regular Rotation: Rotate your API keys periodically for security

• Environment Variables: Consider using environment variables for API keys in production

• Access Control: Only share API keys with trusted team members

Troubleshooting API Key Issues:

• “API key not valid” error: - Verify you copied the API key correctly - Check that the YouTube Data API v3 is enabled in your project - Ensure API key restrictions aren’t blocking your requests

• “Daily quota exceeded” error: - Wait for the quota to reset (24 hours) - Consider increasing your refresh intervals - Upgrade to a paid plan if needed

• “Access denied” error: - Check API key restrictions are configured correctly - Verify the HTTP referrer matches your setup - Ensure you’re using the correct API key for the correct project

Features Enabled: * Multi-channel video monitoring (unlimited channels) * Real-time latest video detection across all channels * Channel-specific and global latest video variables * Automatic video filtering based on keywords * WebSocket integration for live template updates * Chatbot integration with dynamic YouTube variables

PlayStation Network Integration

Prerequisites: * Active PlayStation Network account * PSN username you want to monitor for trophies

⚠️ Important: You must use your own PSN account credentials

Setup Process:

1. Configure Your PSN Account: * In Settings → Service Integrations → PlayStation Network: * Enter YOUR PSN username (the account you want to monitor) * Configure trophy notification preferences * Test the connection * Verify your profile is accessible for trophy tracking

Features Enabled: * Trophy unlock notifications * Game status updates * Achievement progress tracking * Game artwork display

Streamlabs Integration

⚠️ Important: You must have your own accounts with these services

Streamlabs:

Prerequisites: * Active Streamlabs account linked to your streaming platform * Streamlabs dashboard access

Setup Process:

1. Ensure Streamlabs Account Setup: * Visit https://streamlabs.com/ * Sign in with your streaming platform account (Twitch/YouTube) * Complete your Streamlabs dashboard setup

2. Connect to Mycelian: * In Mycelian Settings → Service Integrations → Streamlabs: * Click “Connect to Streamlabs” * Complete OAuth authorization using YOUR Streamlabs account * Configure event preferences * Verify connection status shows “Connected”

OBS Studio Integration

Browser Source Setup

1. Enable Templates: Ensure the Flask server is running (automatic with Mycelian)

2. Add Browser Sources in OBS: * Create new Browser Source * Set URL to http://localhost:5000/{template_name} * Common templates:

   • Alerts: http://localhost:5000/bitboss

   • Activity Feed: http://localhost:5000/activity_feed

   • Chat: http://localhost:5000/chat

   • Now Playing: http://localhost:5000/spotify

3. Configure Source Properties: * Set width/height appropriate for your template

Template Configuration

Custom Sources Tab

Use the Custom Sources tab to configure template appearance:

1. Select Template: Choose from available configurations

2. Edit Properties: Modify colors, fonts, animations, and layout

3. Save Changes: Apply configuration to template files

4. Preview: View changes in real-time

Source Controls Tab

Use the Source Controls tab for real-time interaction:

1. Interactive Elements: Buttons, sliders, toggles for live control

2. Dynamic Updates: Changes reflect immediately in browser sources

3. Template Actions: Trigger animations, reset counters, spin wheels

Connector Automation Setup

Connectors Tab

The Connectors tab provides a powerful automation system for creating trigger-action workflows:

Getting Started with Connectors:

1. Access the Connectors Tab: Open the Connectors tab in the desktop application

2. Create Your First Connector: Click “New Connector” to open the creation dialog

3. Configure Basic Information: * Enter a descriptive name for your connector * Add an optional description explaining what it does

4. Set Up Triggers: * Choose from 15+ trigger types (Twitch events, donations, timers, manual triggers) * Add optional conditions to make triggers more specific * Configure trigger-specific parameters

5. Configure Actions: * Add one or more actions to execute when triggered * Choose from 9+ action types including:

   • Template controls (counters, roulette wheels, etc.)

   • Chat messages with dynamic placeholders

   • API calls to external services

   • File operations and logging

   • System commands and keyboard/mouse input

   • Audio control (volume, microphone)

6. Test Your Connector: * Use the built-in test functionality to verify your connector works * Review the test results and debug any issues * Enable the connector when you’re satisfied it works correctly

Example Connector Workflows:

• High Bits Counter: When someone cheers 100+ bits → increment a counter template

• VIP Follow Response: When a user with “VIP” in their name follows → send a special chat message

• Donation Logger: When someone donates $5+ → write donation details to a log file

• Music Control: When channel points are redeemed for “Next Song” → make API call to skip track

• Alert Trigger: When specific chat command is used → trigger a custom alert animation

Connector Management:

• Statistics: View how often connectors trigger and execute actions

• Enable/Disable: Toggle connectors on/off without deleting them

• Edit: Modify existing connectors with the same interface used for creation

• Delete: Remove connectors you no longer need

• Examples: Use the “Examples” button to create pre-configured sample connectors

Verification

Testing Your Setup

1. Database Connection: Check Settings → Database for green status indicator

2. Service Connections: Verify all integrations show “Connected” status

3. Browser Sources: Add a test browser source in OBS to confirm template loading

4. Alert Testing: Use test buttons in Settings to verify alert functionality

5. WebSocket Communication: Check Activity Feed for real-time event updates

6. Connector Testing: Create a simple test connector and verify it triggers correctly

Troubleshooting

Common Issues

Port Already in Use (5000): * Close other applications using port 5000 * Or modify the port in application settings and update OBS browser source URLs

Database Connection Failed: * For Firebase: Verify key file path and database URL * For SQLite: Check file permissions and path accessibility * Test connection using built-in connection tester

Service Authentication Errors: * Verify API credentials are correct and active * Check OAuth redirect URIs match exactly * Re-authorize connections if tokens expire * Review service-specific permissions and scopes

Browser Sources Not Loading: * Confirm Flask server is running (check Activity Feed tab) * Verify template files exist in templates/ directory * Check browser console for JavaScript errors * Ensure OBS browser source URL format is correct

WebSocket Connection Issues: * Verify web server is running on correct port * Check firewall settings for port 5000 * Review browser console for connection errors * Confirm templates are properly connecting to Socket.IO

Template Controls Not Working: * Check Source Controls tab for registered dynamic controls * Verify template configuration includes dynamic_controls section * Ensure WebSocket events are properly defined * Test with Source Controls tab before using in OBS

Performance Issues: * Close unnecessary browser sources in OBS * Reduce animation complexity in template configurations * Monitor system resources and available RAM * Consider using audio-only alerts for resource-intensive setups

Connector Issues: * Connectors Not Triggering: Verify service integrations are connected and active, check trigger conditions for typos, test with manual trigger events * Actions Not Executing: Review action configuration parameters, check logs for execution errors, verify template names and action IDs are correct * Template Control Actions Failing: Ensure template supports the specified action, verify WebSocket connection is active, check template configuration includes required elements * Test Mode Not Working: Confirm connector is properly saved, check that all required fields are filled, review test data matches trigger expectations

Migration from Other Platforms

Alert Import: * Use Settings → Alert Migration to import from Streamlabs * Backup your current alert configurations before migration * Test imported alerts thoroughly before going live

Database Migration: * Use Settings → Database Migration for switching between Firebase and SQLite * Create backups before starting migration process * Monitor migration progress and logs for any issues

Getting Help

Diagnostic Information: * Check logs/ directory for detailed error messages * Use Settings → Debug Information for system status * Monitor Activity Feed for real-time event processing

Support Resources: * Verify all dependencies are properly installed with uv pip list * Ensure your system meets minimum requirements * Check template configurations for syntax errors * Review WebSocket event logs for communication issues

Log Locations: * Application logs: logs/mycelian.log * Database operations: logs/database.log * WebSocket events: logs/websocket.log