Dev Knowledgebase

Workspace Guidelines

Sun, 31 May 2026 00:00:00 +0000

Repository Guidelines #

1. Workspace & Server Overview #

Development Environment: Running on a remote Debian 12 server (IP: 173.212.213.72, hostname: 0rk.de). The server is equipped with a high-performance multi-core CPU and significant memory, but operates WITHOUT GPU acceleration.
Workspace Architecture: The workspace at /home/dev/ contains multiple independent, fully realized systems rather than a single monorepo. It serves as a unified workspace for audio workstations, Music Information Retrieval (MIR) visualizers, static web hydration frameworks, and various active projects.
Target Guidelines Purpose: This document acts as a master map for AI agents and human developers operating inside /home/dev/ to understand the architecture, run configurations, coding standards, and testing protocols of all active sub-projects.

2. Projects & Architecture #

The workspace is organized into several distinct active domains:

MixBox Guidelines

Sun, 31 May 2026 00:00:00 +0000

Repository Guidelines #

1. Workspace & Server Overview #

Development Environment: Running on a remote Debian 12 server (IP: 173.212.213.72, hostname: 0rk.de). The server is equipped with a high-performance multi-core CPU and significant memory, but operates WITHOUT GPU acceleration.
Workspace Architecture: The workspace at /home/dev/ contains multiple independent, fully realized systems rather than a single monorepo. It serves as a unified workspace for audio workstations, Music Information Retrieval (MIR) visualizers, static web hydration frameworks, and various active projects.
Target Guidelines Purpose: This document acts as a master map for AI agents and human developers operating inside /home/dev/ to understand the architecture, run configurations, coding standards, and testing protocols of all active sub-projects.

2. Projects & Architecture #

The workspace is organized into several distinct active domains:

OMP Dashboard & Telemetry Blueprint

Wed, 10 Jun 2026 00:00:00 +0000

OMP Dashboard & Telemetry Blueprint #

This blueprint outlines the deployment architecture for the OMP Dashboard and OMP Telemetry (Stats) endpoints, their integration with the local agent environment, and how they are securely exposed.

1. Core Architecture #

The system utilizes two primary user-space applications hosted via systemd user services to expose visualization and management layers for active agents.

Pi Agent Dashboard: Serves the UI for managing agents, inspecting sessions, and interacting with the local Pi-AI workspace.
OMP Stats Dashboard: A secondary telemetry visualizer running omp stats.

2. Port and Firewall Configuration #

Backend Port Assignments #

Pi Dashboard backend is bound to 0.0.0.0:45433 (modified via systemd).
OMP Stats backend is bound to :::45434 (modified via systemd).

Nginx Reverse Proxy (Frontend) #

To implement a robust, basic authentication layer without relying on external OAuth providers, Nginx is deployed as a reverse proxy:

🤖 Discord.py × OMP Plugin Cheat Sheet

Mon, 08 Jun 2026 00:00:00 +0000

🤖 Discord.py × OMP Plugin Cheat Sheet #

Bridge a discord.py bot (Python) with the OMP coding agent extension system (Bun/TS) — from zero to full bidirectional integration.

🧠 Core Concept #

OMP extensions = TypeScript/Bun. discord.py = Python. They’re separate runtimes. You bridge them via one of three tiers:

	🪝 Tier 1: Webhook	🔧 Tier 2: MCP Server	🌉 Tier 3: Extension + Bot
Direction	OMP → Discord only	Both (LLM invokes tools)	Both (event-driven)
Needs Python?	❌ No	✅ Yes	✅ Yes
Needs Bot Token?	❌ No (webhook URL)	✅ Yes	✅ Yes
Discord → OMP?	❌	❌	✅
Auto-notify events?	✅	❌	✅
LLM calls Discord?	❌	✅	✅
Setup time	~5 min	~15 min	~30–60 min
Deps	None	`discord.py`, `mcp`	`discord.py`, `aiohttp`

⚡ OMP Extension Contract (All Tiers) #

// ~/.omp/agent/extensions/my-ext/index.ts
import type { ExtensionAPI } from "@oh-my-pi/pi-coding-agent";

export default function myExt(pi: ExtensionAPI) {
  // ── Registration Phase (sync) ──
  pi.setLabel("My Extension");

  pi.on("agent_end", async (event, ctx) => { /* ... */ });
  pi.on("session_start", async (event, ctx) => { /* ... */ });

  pi.registerTool({ name: "my_tool", /* ... */ });
  pi.registerCommand("my-cmd", { /* ... */ });

  // ⚠️ CANNOT call pi.sendMessage() during load — only in handlers
}

📡 Key Lifecycle Events #

session_start → input → agent_start → turn_start
  → tool_call → tool_execution_start → tool_execution_end → tool_result
  → turn_end → agent_end → session_shutdown

Event	Use Case	Return
`agent_end`	“Done” notification to Discord	—
`tool_call`	Audit / block dangerous ops	`{ block, reason }`
`tool_result`	Redact secrets before logging	`{ content }`
`session_start`	Init bot connection	—
`session_shutdown`	Cleanup / final flush	—

🪝 Tier 1 — Webhook (Zero-Dep, 5 min) #

No bot. No Python. Just fetch(). OMP → Discord one-way.

⚡ COMMAND SYSTEM & DECORATORS CHEAT SHEET

Sun, 31 May 2026 00:00:00 +0000

⚡ COMMAND SYSTEM & DECORATORS CHEAT SHEET #

Ultra-Condensed Enlightenment Guide

🎮 COMMAND CLASS HIERARCHY #

🎯 Base Classes: Command, Group, HybridCommand for different command patterns
🔧 Command Types: Regular, Group (subcommands), Hybrid (slash + prefix)
📊 Inheritance: commands.Command → RedCommand → Enhanced functionality
🎨 Factory Pattern: @commands.command() decorator creates Command instances
🔄 Dynamic Creation: Runtime command creation and registration
🛡️ Validation: Comprehensive parameter validation at creation
📦 Metadata: Rich metadata storage for help, examples, usage
🎯 Error Handling: Built-in error handling with customizable responses
🔧 Hooks: Before/after invoke hooks for processing pipeline
📊 Statistics: Command usage tracking and performance metrics

🧩 COMMAND DECORATORS MASTERY #

Core Command Decorators #

@commands.command(name="mycommand", aliases=["mc", "mycmd"])
@commands.guild_only()                    # Guild-only restriction
@commands.dm_only()                       # DM-only restriction
@commands.is_owner()                      # Bot owner only
@commands.admin_or_permissions(manage_guild=True)  # Admin or specific perms
@commands.mod_or_permissions(manage_messages=True) # Mod or specific perms
@commands.has_permissions(kick_members=True)       # Required permissions
@commands.bot_has_permissions(ban_members=True)    # Bot required perms
@commands.cooldown(rate=1, per=30, type=commands.BucketType.user)

Advanced Permission Decorators #

@commands.check(lambda ctx: ctx.author.id in allowed_users)
@commands.check_any(commands.is_owner(), commands.has_role("Admin"))
@commands.has_any_role("Moderator", "Admin", "Staff")
@commands.has_role("VIP")
@commands.bot_has_guild_permissions(manage_roles=True)
@commands.before_invoke(setup_function)
@commands.after_invoke(cleanup_function)

🔧 CONVERTER SYSTEM ARCHITECTURE #

Built-in Converters (20+ Available) #

# Discord Object Converters
discord.Member          # Mentions, names, nicknames, IDs
discord.User            # Global user lookup
discord.TextChannel     # Channel mentions, names, IDs
discord.VoiceChannel    # Voice channel lookup
discord.Role            # Role mentions, names, IDs
discord.Guild           # Guild lookup (bot owner only)
discord.Emoji           # Custom emoji conversion
discord.PartialEmoji    # Any emoji (custom or unicode)
discord.Message         # Message ID or URL conversion
discord.Invite          # Invite code/URL conversion

# Utility Converters
commands.Greedy[Type]   # Consume all remaining args of type
typing.Union[Type1, Type2]  # Try multiple types in order
typing.Optional[Type]   # Optional parameter with None default
commands.Range[int, 1, 100]  # Ranged integer values
commands.Codeblock      # Extract code from codeblocks

Custom Converter Implementation #

class TimeConverter(commands.Converter):
    async def convert(self, ctx, argument):
        # Parse time strings like "1h30m", "2d", "45s"
        match = re.match(r'(\d+)([smhd])', argument.lower())
        if not match:
            raise commands.BadArgument(f"Invalid time format: {argument}")
        
        value, unit = match.groups()
        multipliers = {'s': 1, 'm': 60, 'h': 3600, 'd': 86400}
        return int(value) * multipliers[unit]

# Usage in command
@commands.command()
async def remind(self, ctx, duration: TimeConverter, *, message):
    # duration is now converted to seconds
    pass

🎯 ARGUMENT PARSING MASTERY #

Parameter Types and Patterns #

# Basic parameter types
async def cmd(self, ctx, user: discord.Member, amount: int):
    pass

# Optional parameters with defaults
async def cmd(self, ctx, user: discord.Member = None, amount: int = 10):
    pass

# Variable arguments
async def cmd(self, ctx, *users: discord.Member):
    # users is tuple of all remaining Member arguments
    pass

# Keyword-only arguments (after *)
async def cmd(self, ctx, user: discord.Member, *, reason="No reason"):
    # reason consumes all remaining text as single string
    pass

# Greedy converters
async def cmd(self, ctx, users: commands.Greedy[discord.Member], amount: int = 1):
    # Consumes as many members as possible, then amount
    pass

# Union types (try in order)
async def cmd(self, ctx, target: typing.Union[discord.Member, discord.User]):
    # Try Member first, fallback to User
    pass

Flag System (Advanced) #

class BanFlags(commands.FlagConverter):
    reason: str = commands.flag(description="Reason for ban")
    days: int = commands.flag(default=1, description="Days of messages to delete")
    silent: bool = commands.flag(default=False, description="Silent ban")

@commands.command()
async def ban(self, ctx, member: discord.Member, *, flags: BanFlags):
    # Usage: !ban @user --reason "Spam" --days 7 --silent
    await member.ban(reason=flags.reason, delete_message_days=flags.days)
    if not flags.silent:
        await ctx.send(f"Banned {member} for {flags.reason}")

🔒 PERMISSION CHECK SYSTEM #

Permission Hierarchy #

# Red's Permission Levels (in order)
PrivilegeLevel.NONE         # No special privileges
PrivilegeLevel.MOD          # Moderator level
PrivilegeLevel.ADMIN        # Administrator level  
PrivilegeLevel.GUILD_OWNER  # Guild owner
PrivilegeLevel.BOT_OWNER    # Bot owner (highest)

# Usage in checks
async def has_mod_perms(ctx):
    return await bot.is_mod(ctx.author)

@commands.check(has_mod_perms)
async def modcommand(self, ctx):
    pass

Custom Permission Checks #

def require_channel(*channel_names):
    async def predicate(ctx):
        return ctx.channel.name in channel_names
    return commands.check(predicate)

def require_user_id(*user_ids):
    async def predicate(ctx):
        return ctx.author.id in user_ids
    return commands.check(predicate)

def require_guild_feature(feature):
    async def predicate(ctx):
        return feature in ctx.guild.features
    return commands.check(predicate)

# Usage
@require_channel("bot-commands", "admin")
@require_guild_feature("COMMUNITY")
async def special_command(self, ctx):
    pass

⏰ COOLDOWN SYSTEM ARCHITECTURE #

Bucket Types and Patterns #

# Cooldown bucket types
commands.BucketType.default     # Global cooldown
commands.BucketType.user        # Per-user cooldown
commands.BucketType.guild       # Per-guild cooldown
commands.BucketType.channel     # Per-channel cooldown
commands.BucketType.member      # Per-member (guild+user) cooldown
commands.BucketType.category    # Per-category cooldown
commands.BucketType.role        # Per-role cooldown

# Multiple cooldowns
@commands.cooldown(1, 30, commands.BucketType.user)        # 1 per 30s per user
@commands.cooldown(5, 60, commands.BucketType.guild)       # 5 per 60s per guild
@commands.max_concurrency(1, commands.BucketType.user)     # Max 1 concurrent per user

# Dynamic cooldowns
@commands.dynamic_cooldown(lambda ctx: get_user_cooldown(ctx.author))
async def dynamic_cmd(self, ctx):
    pass

Cooldown Management #

# Reset cooldowns
command.reset_cooldown(ctx)                    # Reset for context
command.get_cooldown_retry_after(ctx)         # Get remaining time
bucket = command._buckets.get_bucket(ctx.message)  # Get bucket
bucket.reset()                                 # Reset bucket

# Custom cooldown handling
@commands.Cog.listener()
async def on_command_error(self, ctx, error):
    if isinstance(error, commands.CommandOnCooldown):
        await ctx.send(f"Cooldown: {error.retry_after:.1f}s remaining")

📋 HELP SYSTEM INTEGRATION #

Help Command Customization #

class CustomHelpCommand(commands.DefaultHelpCommand):
    def __init__(self):
        super().__init__(
            command_attrs={
                "help": "Shows help for commands",
                "cooldown": commands.Cooldown(1, 3, commands.BucketType.user)
            }
        )
    
    async def send_bot_help(self, mapping):
        # Custom bot help implementation
        pass
    
    async def send_cog_help(self, cog):
        # Custom cog help implementation
        pass
    
    async def send_command_help(self, command):
        # Custom command help implementation
        pass

# Set custom help
bot.help_command = CustomHelpCommand()

Help Documentation Patterns #

@commands.command(
    brief="Short description for help list",
    help="Long detailed description with examples",
    usage="<required_arg> [optional_arg]",
    aliases=["alias1", "alias2"]
)
async def example(self, ctx, required_arg, optional_arg="default"):
    """
    Docstring provides additional help information.
    
    Examples:
        !example hello
        !example hello world
    """
    pass

🎪 COMMAND GROUPS & SUBCOMMANDS #

Group Command Structure #

@commands.group(name="config", invoke_without_command=True)
async def config_group(self, ctx):
    """Main config command - shows help if no subcommand"""
    if ctx.invoked_subcommand is None:
        await ctx.send_help(ctx.command)

@config_group.command(name="set")
async def config_set(self, ctx, setting, value):
    """Subcommand: !config set prefix !"""
    pass

@config_group.command(name="get")
async def config_get(self, ctx, setting):
    """Subcommand: !config get prefix"""
    pass

@config_group.group(name="roles")
async def config_roles(self, ctx):
    """Nested group: !config roles"""
    pass

@config_roles.command(name="add")
async def config_roles_add(self, ctx, role):
    """Nested subcommand: !config roles add @role"""
    pass

🔄 HYBRID COMMANDS (Slash + Prefix) #

@commands.hybrid_command(name="info")
async def info_command(self, ctx, user: discord.Member = None):
    """Works as both !info and /info"""
    user = user or ctx.author
    embed = discord.Embed(title=f"Info for {user}")
    await ctx.send(embed=embed)

@commands.hybrid_group(name="moderation")
async def mod_group(self, ctx):
    """Hybrid group for moderation commands"""
    pass

@mod_group.command(name="ban")
async def ban_hybrid(self, ctx, member: discord.Member, *, reason="No reason"):
    """Hybrid ban command: !moderation ban or /moderation ban"""
    await member.ban(reason=reason)
    await ctx.send(f"Banned {member}")

🛠️ COMMAND LIFECYCLE HOOKS #

async def command_before_invoke(self, ctx):
    """Runs before every command in this cog"""
    print(f"Command {ctx.command} invoked by {ctx.author}")
    # Log command usage
    await self.log_command_usage(ctx)

async def command_after_invoke(self, ctx):
    """Runs after every command in this cog"""
    print(f"Command {ctx.command} completed")
    # Update command statistics
    await self.update_command_stats(ctx)

@commands.before_invoke(command_before_invoke)
@commands.after_invoke(command_after_invoke)
@commands.command()
async def tracked_command(self, ctx):
    """Command with before/after hooks"""
    await ctx.send("Command executed!")

# Global hooks (in cog)
async def cog_before_invoke(self, ctx):
    """Runs before any command in this cog"""
    pass

async def cog_after_invoke(self, ctx):
    """Runs after any command in this cog"""  
    pass

🔍 ERROR HANDLING MASTERY #

@commands.Cog.listener()
async def on_command_error(self, ctx, error):
    """Comprehensive error handling"""
    if isinstance(error, commands.CommandNotFound):
        return  # Ignore command not found
    
    elif isinstance(error, commands.MissingRequiredArgument):
        await ctx.send(f"Missing argument: {error.param}")
        await ctx.send_help(ctx.command)
    
    elif isinstance(error, commands.BadArgument):
        await ctx.send(f"Invalid argument: {error}")
        await ctx.send_help(ctx.command)
    
    elif isinstance(error, commands.CheckFailure):
        await ctx.send("You don't have permission to use this command")
    
    elif isinstance(error, commands.CommandOnCooldown):
        await ctx.send(f"Cooldown: {error.retry_after:.1f}s remaining")
    
    elif isinstance(error, commands.MaxConcurrencyReached):
        await ctx.send("Command is already running. Please wait.")
    
    else:
        # Log unexpected errors
        print(f"Unexpected error in {ctx.command}: {error}")

⚡ QUICK COMMAND REFERENCE #

# Basic Command
@commands.command(name="ping", aliases=["p"])
async def ping(self, ctx):
    await ctx.send("Pong!")

# Command with Arguments
@commands.command()
async def say(self, ctx, *, message):
    await ctx.send(message)

# Permission Check
@commands.has_permissions(manage_messages=True)
@commands.command()
async def clear(self, ctx, amount: int = 10):
    await ctx.channel.purge(limit=amount)

# Cooldown
@commands.cooldown(1, 30, commands.BucketType.user)
@commands.command()
async def daily(self, ctx):
    # Give daily reward
    pass

# Group with Subcommands
@commands.group()
async def settings(self, ctx):
    if ctx.invoked_subcommand is None:
        await ctx.send_help(ctx.command)

@settings.command()
async def prefix(self, ctx, new_prefix):
    # Set new prefix
    pass

⚡ Commands are the interface between users and your bot. Master this system for intuitive user experiences.

⚡️ Content Delivery Network (CDN) Speedrun

Sun, 31 May 2026 00:00:00 +0000

⚡️ Content Delivery Network (CDN) Speedrun #

Your ultra-quick guide to understanding how CDNs make the web faster and more reliable.

🤔 1. What is a CDN? #

A Content Delivery Network (CDN) is a globally distributed network of servers designed to deliver web content to users as quickly, cheaply, and reliably as possible. Instead of all users accessing one central server, a CDN allows them to access a copy of the content from a server that is geographically closer to them.

⚡ Musical Arousal: The Energy of Music

Sun, 31 May 2026 00:00:00 +0000

⚡ Musical Arousal: The Energy of Music #

Arousal is the energy or intensity of a piece of music. It’s on a scale from calm/sleepy 😴 to energetic/intense 💥.

Think of it as the physical energy that makes you want to relax or move.

⚖️ The Arousal Scale #

Low Arousal: Songs that feel calm, soothing, or gentle.
- Keywords: Relaxing, Peaceful, Mellow, Ambient
- Example: An ambient soundscape or a soft acoustic lullaby.
High Arousal: Songs that feel energetic, powerful, or intense.

⚡ RED-DISCORDBOT BACKGROUND TASKS MASTERY

Sun, 31 May 2026 00:00:00 +0000

⚡ RED-DISCORDBOT BACKGROUND TASKS MASTERY #

Ultra-Condensed Enlightenment Guide - Real Red Patterns

🚀 RED COG TASK LIFECYCLE #

🎯 Cog Methods: cog_load() for task creation, cog_unload() for cleanup
🔧 Task Storage: Store as instance attributes: self.task_name = None
📊 Red Ready Pattern: await self.bot.wait_until_red_ready() before operations
🎨 Bot Closed Check: while not self.bot.is_closed(): for main loops
🔄 Task Creation: asyncio.create_task() in cog_load() method
🛡️ Cleanup Pattern: task.cancel() in cog_unload() if not done
📦 Logging Setup: log = logging.getLogger("red.cogs.cogname")
🎯 Exception Handling: Try/except with proper logging in task loops

import asyncio
import logging
from redbot.core import commands

log = logging.getLogger("red.cogs.mycog")

class MyCog(commands.Cog):
    def __init__(self, bot):
        self.bot = bot
        self.background_task = None
    
    async def cog_load(self):
        """Red's cog initialization method"""
        self.background_task = asyncio.create_task(self._background_loop())
    
    def cog_unload(self):
        """Red's cog cleanup method"""
        if self.background_task and not self.background_task.done():
            self.background_task.cancel()
    
    async def _background_loop(self):
        """Main background task loop"""
        await self.bot.wait_until_red_ready()
        while not self.bot.is_closed():
            try:
                await self._do_work()
                await asyncio.sleep(60)
            except Exception as e:
                log.exception("Background task error: %s", e)
                await asyncio.sleep(300)  # Error recovery delay

🔄 RED CONFIG INTEGRATION PATTERNS #

🎯 Config Access: Use self.config for dynamic settings in tasks
🔧 Guild-Specific Tasks: Check guild configs in loops
📊 Dynamic Intervals: Read timer values from config
🎨 Feature Toggles: Enable/disable features via config
🔄 Config Watching: React to config changes during execution
🛡️ Default Fallbacks: Use sensible defaults when config missing
📦 Batch Config Reads: Cache config values for performance
🎯 Cross-Guild Processing: Handle multiple guild configurations

async def _stream_monitoring_loop(self):
    """Real pattern from Streams cog"""
    await self.bot.wait_until_red_ready()
    while not self.bot.is_closed():
        try:
            # Get dynamic timer from config
            timer = await self.config.refresh_timer()
            if timer < 60:
                timer = 60  # Minimum interval
            
            # Process all guilds
            for guild in self.bot.guilds:
                guild_config = self.config.guild(guild)
                if await guild_config.enabled():
                    await self._check_guild_streams(guild)
            
            await asyncio.sleep(timer)
        except Exception as error:
            log.exception("Stream monitoring error: %s", error)
            await asyncio.sleep(300)

async def _check_guild_streams(self, guild):
    """Process streams for specific guild"""
    streams = await self.config.guild(guild).streams()
    for stream_data in streams:
        try:
            await self._process_single_stream(guild, stream_data)
        except Exception as e:
            log.error("Failed to check stream in %s: %s", guild.name, e)

🏗️ COMPLEX COG INITIALIZATION #

🎯 Multi-Phase Setup: Database → API → Services → Background tasks
🔧 Resource Management: Database connections, HTTP sessions, APIs
📊 Migration Handling: Schema updates during initialization
🎨 Dependency Loading: Wait for required cogs/services
🔄 Event Coordination: Use asyncio.Event() for readiness signaling
🛡️ Failure Recovery: Graceful degradation when components fail
📦 Data Path Usage: cog_data_path(self) for file storage
🎯 Version Management: Handle schema/data version upgrades

from redbot.core.data_manager import cog_data_path
from redbot.core.utils.common_filters import escape_spoilers_and_mass_mentions

class AudioCog(commands.Cog):
    def __init__(self, bot):
        self.bot = bot
        self.session = None
        self.db_conn = None
        self.api_interface = None
        self.playlist_api = None
        self.cog_ready_event = asyncio.Event()
        self.player_automated_timer_task = None
    
    async def cog_load(self):
        """Complex initialization from Audio cog"""
        self.session = aiohttp.ClientSession()
        asyncio.create_task(self.initialize())
    
    async def initialize(self):
        await self.bot.wait_until_red_ready()
        try:
            # Phase 1: Database
            db_path = cog_data_path(self) / "Audio.db"
            self.db_conn = APSWConnectionWrapper(str(db_path))
            
            # Phase 2: API Setup
            self.api_interface = AudioAPIInterface(
                self.bot, self.config, self.session, self.db_conn
            )
            await self.api_interface.initialize()
            
            # Phase 3: Services
            self.playlist_api = PlaylistWrapper(
                self.bot, self.config, self.db_conn
            )
            await self.playlist_api.init()
            
            # Phase 4: Migration
            await self.data_schema_migration()
            
            # Phase 5: Background tasks
            self.player_automated_timer_task = asyncio.create_task(
                self.player_automated_timer()
            )
            
            # Signal ready
            self.cog_ready_event.set()
            
        except Exception as exc:
            log.critical("Audio cog initialization failed: %s", exc)

🛡️ RED ERROR HANDLING PATTERNS #

🎯 Exception Isolation: Individual task failures don’t crash cog
🔧 Red Logging: Use log.exception() with proper logger names
📊 Guild-Specific Errors: Continue processing other guilds on failure
🎨 API Rate Limits: Handle Discord API and external API limits
🔄 Exponential Backoff: Increase delays for persistent failures
🛡️ Resource Cleanup: Ensure connections/sessions are closed
📦 Error Context: Include guild/user/command context in logs
🎯 Graceful Degradation: Disable features on repeated failures

async def _robust_api_task(self):
    """Production-ready error handling"""
    consecutive_failures = 0
    base_delay = 60
    max_delay = 3600  # 1 hour max
    
    while not self.bot.is_closed():
        try:
            await self._perform_api_work()
            consecutive_failures = 0  # Reset on success
            await asyncio.sleep(base_delay)
            
        except aiohttp.ClientError as e:
            consecutive_failures += 1
            delay = min(base_delay * (2  consecutive_failures), max_delay)
            log.warning(
                "API error (attempt %d), retrying in %ds: %s",
                consecutive_failures, delay, e
            )
            await asyncio.sleep(delay)
            
        except discord.HTTPException as e:
            if e.status == 429:  # Rate limited
                retry_after = e.response.headers.get('Retry-After', 60)
                log.warning("Discord rate limit, waiting %s seconds", retry_after)
                await asyncio.sleep(float(retry_after))
            else:
                log.error("Discord API error: %s", e)
                await asyncio.sleep(300)
                
        except Exception as e:
            log.exception("Unexpected error in background task: %s", e)
            await asyncio.sleep(600)  # Long delay for unknown errors

📊 RED PERFORMANCE PATTERNS #

🎯 AsyncIter Usage: redbot.core.utils.AsyncIter for large datasets
🔧 Batch Processing: Process multiple items together efficiently
📊 Connection Reuse: Single aiohttp session per cog
🎨 Cache Integration: Use Red’s config caching features
🔄 Memory Management: Explicit cleanup of large objects
🛡️ Concurrency Limits: Prevent overwhelming Discord API
📦 Lazy Loading: Defer expensive operations until needed
🎯 Resource Pooling: Reuse expensive resources across tasks

from redbot.core.utils import AsyncIter
import aiohttp

async def process_large_guild_list(self, guilds):
    """Efficient processing using Red's AsyncIter"""
    # Process guilds in batches
    async for batch in AsyncIter(guilds, steps=10):
        tasks = []
        for guild in batch:
            # Limit concurrent operations
            if len(tasks) >= 5:
                results = await asyncio.gather(*tasks, return_exceptions=True)
                for result in results:
                    if isinstance(result, Exception):
                        log.error("Guild processing error: %s", result)
                tasks = []
            
            task = asyncio.create_task(self._process_guild(guild))
            tasks.append(task)
        
        # Process remaining tasks
        if tasks:
            await asyncio.gather(*tasks, return_exceptions=True)
        
        # Yield control to other tasks
        await asyncio.sleep(0)

async def _process_guild(self, guild):
    """Process individual guild with rate limiting"""
    try:
        # Use cached config when possible
        config = self.config.guild(guild)
        settings = await config.all()  # Single config call
        
        if not settings.get('enabled', False):
            return
        
        # Process guild data
        await self._do_guild_work(guild, settings)
        
    except Exception as e:
        log.error("Failed to process guild %s (%d): %s", 
                 guild.name, guild.id, e)

🔄 RED TASK COORDINATION #

🎯 Cog Dependencies: Wait for other cogs to be ready
🔧 Event Coordination: Use asyncio.Event() for synchronization
📊 Queue Processing: Handle command queues and work items
🎨 Lock Usage: Protect shared resources with asyncio.Lock()
🔄 Condition Variables: Complex state coordination
🛡️ Semaphore Limits: Control concurrent operations
📦 Cross-Cog Communication: Safe inter-cog task coordination
🎯 Bot Event Integration: React to Discord events in tasks

class CoordinatedCog(commands.Cog):
    def __init__(self, bot):
        self.bot = bot
        self.ready_event = asyncio.Event()
        self.work_queue = asyncio.Queue()
        self.processing_lock = asyncio.Lock()
        self.worker_semaphore = asyncio.Semaphore(3)
        
    async def cog_load(self):
        # Start coordinator tasks
        asyncio.create_task(self._producer_task())
        asyncio.create_task(self._worker_task())
        asyncio.create_task(self._monitor_task())
    
    async def _producer_task(self):
        """Generate work items"""
        await self.bot.wait_until_red_ready()
        self.ready_event.set()
        
        while not self.bot.is_closed():
            # Check for new work from config/events
            work_items = await self._generate_work()
            for item in work_items:
                await self.work_queue.put(item)
            await asyncio.sleep(30)
    
    async def _worker_task(self):
        """Process work items with coordination"""
        await self.ready_event.wait()
        
        while not self.bot.is_closed():
            try:
                # Get work with timeout
                work_item = await asyncio.wait_for(
                    self.work_queue.get(), timeout=5.0
                )
                
                # Process with semaphore limiting
                async with self.worker_semaphore:
                    await self._process_work_item(work_item)
                    
            except asyncio.TimeoutError:
                continue  # No work available
            except Exception as e:
                log.exception("Worker task error: %s", e)

# React to Discord events in background tasks
@commands.Cog.listener()
async def on_guild_join(self, guild):
    """Trigger background processing for new guild"""
    if hasattr(self, 'work_queue'):
        await self.work_queue.put(('new_guild', guild))

🎯 RED LIFECYCLE BEST PRACTICES #

🎯 Proper Cleanup: Always cancel tasks in cog_unload()
🔧 Resource Management: Close aiohttp sessions and database connections
📊 Graceful Shutdown: Allow current operations to complete
🎨 State Persistence: Save important state before shutdown
🔄 Restart Recovery: Handle bot restarts gracefully
🛡️ Timeout Handling: Force cleanup if graceful shutdown fails
📦 Memory Cleanup: Clear large data structures
🎯 Event Cleanup: Remove event listeners if needed

class LifecycleCog(commands.Cog):
    def __init__(self, bot):
        self.bot = bot
        self.session = None
        self.db_conn = None
        self.background_tasks = []
        self.shutdown_event = asyncio.Event()
    
    async def cog_load(self):
        """Initialize resources and tasks"""
        self.session = aiohttp.ClientSession()
        
        # Create and track all background tasks
        tasks = [
            asyncio.create_task(self._main_loop()),
            asyncio.create_task(self._cleanup_loop()),
            asyncio.create_task(self._monitor_loop())
        ]
        self.background_tasks.extend(tasks)
    
    def cog_unload(self):
        """Clean shutdown of all resources"""
        log.info("Shutting down %s cog", self.__class__.__name__)
        
        # Signal shutdown to all tasks
        self.shutdown_event.set()
        
        # Cancel all background tasks
        for task in self.background_tasks:
            if not task.done():
                task.cancel()
        
        # Schedule resource cleanup
        asyncio.create_task(self._cleanup_resources())
    
    async def _cleanup_resources(self):
        """Clean up resources with timeout"""
        try:
            # Wait for tasks to complete gracefully
            if self.background_tasks:
                await asyncio.wait_for(
                    asyncio.gather(*self.background_tasks, return_exceptions=True),
                    timeout=10.0
                )
        except asyncio.TimeoutError:
            log.warning("Some background tasks didn't complete in time")
        
        # Close external resources
        if self.session and not self.session.closed:
            await self.session.close()
        
        if self.db_conn:
            self.db_conn.close()
        
        log.info("Cog cleanup completed")
    
    async def _main_loop(self):
        """Main task with shutdown awareness"""
        await self.bot.wait_until_red_ready()
        
        while not self.bot.is_closed() and not self.shutdown_event.is_set():
            try:
                await self._do_work()
                
                # Use shutdown event for early termination
                try:
                    await asyncio.wait_for(
                        self.shutdown_event.wait(), timeout=60.0
                    )
                    break  # Shutdown requested
                except asyncio.TimeoutError:
                    continue  # Normal operation
                    
            except Exception as e:
                log.exception("Main loop error: %s", e)
                if not self.shutdown_event.is_set():
                    await asyncio.sleep(300)

💡 REAL RED PATTERNS IN PRODUCTION #

🎯 Audio Queue Management: Complex state with player coordination
🔧 Stream Monitoring: Multi-platform API polling with caching
📊 Economy Tasks: Transaction processing and interest calculations
🎨 Moderation Automation: Automated actions based on user behavior
🔄 Trivia Timing: Game state management with timeouts
🛡️ Bank Operations: Atomic transactions with rollback support
📦 Playlist Management: Background playlist processing and caching
🎯 Auto-Moderation: Real-time message analysis and action

# Real Audio cog pattern - Player automation
async def player_automated_timer(self):
    """From Audio cog - manages player timeouts"""
    await self.bot.wait_until_red_ready()
    await self.cog_ready_event.wait()
    
    while not self.bot.is_closed():
        try:
            # Check all active players
            for guild_id, player in self.players.copy().items():
                try:
                    if await self._should_disconnect_player(player):
                        await player.stop()
                        await player.disconnect()
                except Exception as e:
                    log.error("Player cleanup error for guild %d: %s", guild_id, e)
            
            await asyncio.sleep(60)  # Check every minute
            
        except Exception as e:
            log.exception("Player timer error: %s", e)
            await asyncio.sleep(300)

# Real Bank cog pattern - Interest calculation
async def _interest_loop(self):
    """Background interest calculation"""
    await self.bot.wait_until_red_ready()
    
    while not self.bot.is_closed():
        try:
            # Calculate interest for all users
            interest_rate = await self.config.interest_rate()
            if interest_rate > 0:
                async for user_data in self._get_all_user_accounts():
                    await self._apply_interest(user_data, interest_rate)
            
            # Wait until next interest period
            next_run = await self._calculate_next_interest_time()
            await asyncio.sleep(next_run)
            
        except Exception as e:
            log.exception("Interest calculation error: %s", e)
            await asyncio.sleep(3600)  # Retry in 1 hour

⚡ Master Red-DiscordBot’s proven background task patterns for rock-solid, efficient, and maintainable cog operations!

⚡ RED-DISCORDBOT DEVELOPER QUICK REFERENCE ⚡

Sun, 31 May 2026 00:00:00 +0000

⚡ RED-DISCORDBOT DEVELOPER QUICK REFERENCE ⚡ #

Instant Access Cheat Sheet

🚀 INSTANT SETUP #

pip install Red-DiscordBot
redbot-setup                # Interactive setup
redbot <instance_name>      # Launch bot

🔑 ESSENTIAL IMPORTS #

from redbot.core import commands, Config, bank
from redbot.core.bot import Red
from redbot.core.utils.chat_formatting import box, pagify
from discord.ext import commands as dpy_commands

🧩 COG TEMPLATE #

import discord
from redbot.core import commands, Config

class MyCog(commands.Cog):
    def __init__(self, bot):
        self.bot = bot
        self.config = Config.get_conf(self, identifier=1234567890)
        default_guild = {"setting": "default_value"}
        self.config.register_guild(**default_guild)
    
    @commands.command()
    async def mycommand(self, ctx):
        """Command description"""
        await ctx.send("Response")

📊 CONFIG PATTERNS #

# Basic config setup
self.config = Config.get_conf(self, identifier=12345)
self.config.register_global(setting=default)
self.config.register_guild(guild_setting=default)
self.config.register_user(user_setting=default)

# Get/Set values
value = await self.config.setting()
await self.config.setting.set(new_value)

# Nested data
async with self.config.guild(guild).nested() as data:
    data["key"] = "value"

🛡️ PERMISSION DECORATORS #

@commands.admin()           # Admin only
@commands.mod()             # Moderator+
@commands.guild_only()      # Guild only
@commands.bot_has_permissions(manage_roles=True)
@commands.has_permissions(kick_members=True)

💰 ECONOMY INTEGRATION #

from redbot.core import bank

# Check balance
balance = await bank.get_balance(user)

# Transfer credits
await bank.deposit_credits(user, amount)
await bank.withdraw_credits(user, amount)

# Cost decorator
@bank.cost(100)
async def expensive_command(self, ctx):
    pass

🎯 COMMAND TYPES #

# Basic command
@commands.command()
async def basic(self, ctx, arg):
    pass

# Group command
@commands.group()
async def group(self, ctx):
    pass

@group.command()
async def subcommand(self, ctx):
    pass

# Hybrid command (slash + prefix)
@commands.hybrid_command()
async def hybrid(self, ctx, arg: str):
    pass

🔧 CONVERTERS #

@commands.command()
async def cmd(self, ctx, user: discord.Member, amount: int):
    pass

# Custom converter
class MyConverter(commands.Converter):
    async def convert(self, ctx, argument):
        return processed_argument

📝 EMBED PATTERNS #

embed = discord.Embed(
    title="Title",
    description="Description",
    color=await ctx.embed_color()
)
embed.add_field(name="Field", value="Value", inline=False)
await ctx.send(embed=embed)

🎨 FORMATTING UTILITIES #

from redbot.core.utils.chat_formatting import box, pagify, humanize_list

# Code blocks
await ctx.send(box("code", lang="python"))

# Pagination
for page in pagify(long_text):
    await ctx.send(page)

# Lists
await ctx.send(humanize_list(["item1", "item2", "item3"]))

🔄 EVENT HANDLING #

@commands.Cog.listener()
async def on_message(self, message):
    if message.author.bot:
        return
    # Handle message

@commands.Cog.listener()
async def on_member_join(self, member):
    # Handle new member
    pass

🗂️ DATA SCOPES #

GLOBAL - Bot-wide settings
GUILD - Per-server settings
CHANNEL - Per-channel settings
USER - Per-user settings (global)
MEMBER - Per-member settings (guild-specific)
ROLE - Per-role settings
CUSTOM - Custom identifier

🔍 ERROR HANDLING #

@commands.command()
async def cmd(self, ctx):
    try:
        # Command logic
        pass
    except commands.BadArgument:
        await ctx.send("Invalid argument!")
    except Exception as e:
        await ctx.send(f"Error: {e}")

📦 COG LIFECYCLE #

async def cog_load(self):
    """Called when cog is loaded"""
    pass

async def cog_unload(self):
    """Called when cog is unloaded"""
    pass

def cog_check(self, ctx):
    """Check for all commands in cog"""
    return True

🎵 AUDIO COG BASICS #

from redbot.cogs.audio.core.abc import MixinMeta

class AudioCog(MixinMeta):
    def __init__(self, bot):
        self.bot = bot
        super().__init__()

🔧 DEBUGGING TIPS #

Use [p]load dev for development tools
[p]reload cog_name to reload cog during development
Check logs in data directory
Use print() statements for quick debugging
await ctx.tick() for success confirmation

📚 KEY DOCUMENTATION PATHS #

Official Docs: docs.discord.red
API Reference: redbot.readthedocs.io
Cog Creation Guide: docs.discord.red/en/stable/guide_cog_creation.html
Config Tutorial: docs.discord.red/en/stable/framework_config.html

🚨 COMMON GOTCHAS #

Always use ctx.send() instead of channel.send() when possible
Register config defaults before first access
Use guild_only() for guild-specific commands
Check permissions before attempting Discord actions
Use async context managers for config modifications

⚡ Keep this reference handy for rapid Red-DiscordBot development

⚡ SLASH COMMANDS & MODERN INTERACTIONS CHEAT SHEET

Sun, 31 May 2026 00:00:00 +0000

⚡ SLASH COMMANDS & MODERN INTERACTIONS CHEAT SHEET #

Ultra-Condensed Enlightenment Guide

🚀 HYBRID COMMAND ARCHITECTURE #

🎯 Core Framework: Red’s HybridCommand & HybridGroup classes extending discord.py 2.0
🔧 Dual Nature: Commands work as both prefix commands and slash commands simultaneously
📊 Command Tree: RedTree class manages global app command registration and sync
🎨 Auto-Sync: Built-in sync management with guild-specific and global command handling
🔄 State Management: Disabled commands stored separately for dynamic enable/disable
🛡️ Permission Inheritance: Slash commands inherit Red’s permission system automatically
📦 Error Handling: Specialized error handlers for interaction-specific failures
🎯 Context Adaptation: Commands receive appropriate Context for prefix or Interaction for slash

Hybrid Command Definition #

@commands.hybrid_command(name="example")
async def example_cmd(self, ctx: commands.Context, user: discord.Member):
    \"\"\"Example hybrid command that works as both prefix and slash\"\"\"
    await ctx.send(f"Hello {user.mention}!")

@commands.hybrid_group(name="config")
async def config_group(self, ctx: commands.Context):
    \"\"\"Hybrid group with subcommands\"\"\"
    if ctx.invoked_subcommand is None:
        await ctx.send_help(ctx.command)

@config_group.command(name="set")
async def config_set(self, ctx: commands.Context, option: str, value: str):
    \"\"\"Set configuration option\"\"\"
    await ctx.send(f"Set {option} to {value}")

🎯 APP COMMAND OPTIMIZATION #

Parameter Decoration & Types #

@app_commands.describe(
    user="The user to greet",
    message="Custom greeting message",
    private="Send as ephemeral message"
)
@commands.hybrid_command()
async def greet(
    self, 
    ctx: commands.Context,
    user: discord.Member,
    message: str = "Hello!",
    private: bool = False
):
    await ctx.send(message, ephemeral=private)

Advanced Parameter Patterns #

🔧 Type Hints: Union types, Optional parameters, Literal enums
📊 Range Validation: app_commands.Range[int, 1, 100] for bounded integers
🎨 Transform System: Custom transformers for complex data conversion
🔄 Choice Lists: app_commands.Choice for predefined option sets
🛡️ Permission Checks: Inherit Red’s @commands.has_permissions system
📦 Context Types: Context.interaction property for slash-specific behavior

🤖 AUTOCOMPLETION MASTERY #

Dynamic Autocompletion #

@app_commands.autocomplete(option_name='autocomplete_function')
@commands.hybrid_command()
async def search(self, ctx: commands.Context, query: str):
    \"\"\"Command with autocomplete\"\"\"
    await ctx.send(f"Searching for: {query}")

async def autocomplete_function(
    self, 
    interaction: discord.Interaction, 
    current: str
) -> List[app_commands.Choice[str]]:
    \"\"\"Provide dynamic autocomplete options\"\"\"
    options = await self.get_search_options(current)
    return [
        app_commands.Choice(name=option.name, value=option.id)
        for option in options[:25]  # Max 25 choices
    ]

Autocompletion Best Practices #

🎯 Response Time: Keep autocomplete functions under 3 seconds
🔧 Caching: Cache frequently used autocomplete data
📊 Filtering: Filter results based on current input
🎨 Contextual: Consider guild, user permissions in autocomplete
🔄 Error Handling: Graceful fallbacks for autocomplete failures
🛡️ Rate Limiting: Avoid excessive API calls in autocomplete
📦 Relevance: Sort results by relevance to user input

🌐 LOCALIZATION & INTERNATIONALIZATION #

Command Localization #

from discord import app_commands, Locale

@app_commands.describe(
    user=app_commands.locale_str("user_description", key="USER_DESC"),
    amount=app_commands.locale_str("amount_description", key="AMOUNT_DESC")
)
@commands.hybrid_command(
    name=app_commands.locale_str("pay", key="PAY_COMMAND")
)
async def pay_command(self, ctx, user: discord.Member, amount: int):
    \"\"\"Localized payment command\"\"\"
    await ctx.send(f"Paid {amount} to {user}")

Localization Patterns #

🎯 Locale Support: Support for discord.Locale enum values
🔧 Key Management: Centralized translation key systems
📊 Fallback Logic: English fallbacks for missing translations
🎨 Dynamic Content: Localize response messages not just command descriptions
🔄 Context Awareness: Use interaction.locale for user-specific language
🛡️ Guild Preferences: Respect guild language settings where applicable

🔐 ADVANCED PERMISSION PATTERNS #

Slash-Specific Permission Checks #

@app_commands.default_permissions(manage_guild=True)
@app_commands.guild_only()
@commands.hybrid_command()
async def admin_only(self, ctx: commands.Context):
    \"\"\"Admin-only command with app command permissions\"\"\"
    await ctx.send("Admin command executed!")

# Custom interaction checks
async def is_moderator(interaction: discord.Interaction) -> bool:
    \"\"\"Custom check for moderator role\"\"\"
    return any(role.name == "Moderator" for role in interaction.user.roles)

@app_commands.check(is_moderator)
@commands.hybrid_command()
async def moderate(self, ctx: commands.Context):
    \"\"\"Moderator command with custom check\"\"\"
    await ctx.send("Moderation action performed!")

Permission Integration Patterns #

🎯 Default Permissions: Set initial permission state for commands
🔧 Guild Override: Allow guild admins to customize command permissions
📊 Role-Based: Integrate with Discord’s role permission system
🎨 Dynamic Checks: Runtime permission validation
🔄 Red Integration: Leverage Red’s existing permission framework
🛡️ Inheritance: Command group permissions cascade to subcommands

⚡ INTERACTION RESPONSE PATTERNS #

Response Type Mastery #

@commands.hybrid_command()
async def interactive(self, ctx: commands.Context):
    if ctx.interaction:
        # Slash command - use interaction response
        await ctx.interaction.response.send_message("Processing...", ephemeral=True)
        await asyncio.sleep(2)
        await ctx.interaction.edit_original_response(content="Complete!")
    else:
        # Prefix command - normal response
        message = await ctx.send("Processing...")
        await asyncio.sleep(2)
        await message.edit(content="Complete!")

# Deferred responses for long operations
@commands.hybrid_command()
async def long_task(self, ctx: commands.Context):
    if ctx.interaction:
        await ctx.interaction.response.defer()
        # Long processing...
        await ctx.interaction.followup.send("Task completed!")
    else:
        async with ctx.typing():
            # Long processing...
            await ctx.send("Task completed!")

Response Optimization #

🎯 Response Time: Always respond within 3 seconds or defer
🔧 Ephemeral Messages: Use ephemeral for error/confirmation messages
📊 Edit Patterns: Edit original response instead of sending followups
🎨 Rich Content: Leverage embeds, files, views in responses
🔄 Error Recovery: Handle interaction timeouts gracefully
🛡️ State Tracking: Track interaction response state properly

🛠️ ERROR HANDLING & DEBUGGING #

Slash Command Error Patterns #

class MyCog(commands.Cog):
    @commands.Cog.listener()
    async def on_app_command_error(
        self, 
        interaction: discord.Interaction, 
        error: app_commands.AppCommandError
    ):
        \"\"\"Handle app command specific errors\"\"\"
        if isinstance(error, app_commands.CommandOnCooldown):
            await interaction.response.send_message(
                f"Command on cooldown. Retry in {error.retry_after:.1f}s",
                ephemeral=True
            )
        elif isinstance(error, app_commands.MissingPermissions):
            await interaction.response.send_message(
                "You don't have permission to use this command",
                ephemeral=True
            )
        else:
            # Log unexpected errors
            logger.exception("Unexpected app command error", exc_info=error)

Debug & Development Tools #

🎯 Sync Management: Use bot’s sync command to deploy changes
🔧 Guild Testing: Test commands in development guilds first
📊 Interaction Logging: Log interaction details for debugging
🎨 Error Tracking: Comprehensive error logging and user feedback
🔄 Validation: Type checking and parameter validation
🛡️ Graceful Degradation: Fallback behavior for interaction failures

🚀 PERFORMANCE & SCALABILITY #

Command Tree Optimization #

🎯 Selective Sync: Sync only changed commands, not entire tree
🔧 Guild Isolation: Separate guild-specific from global commands
📊 Command Grouping: Organize related commands into logical groups
🎨 Lazy Loading: Load command data only when needed
🔄 Cache Strategy: Cache command metadata and permissions
🛡️ Rate Limiting: Respect Discord’s command sync rate limits
📦 Memory Management: Clean up unused command references

Advanced Patterns #

# Command with complex parameter handling
@app_commands.describe(
    action=app_commands.locale_str("The action to perform"),
    target=app_commands.locale_str("The target for the action")
)
@app_commands.choices(action=[
    app_commands.Choice(name="kick", value="kick"),
    app_commands.Choice(name="ban", value="ban"),
    app_commands.Choice(name="timeout", value="timeout")
])
@commands.hybrid_command()
async def moderate_user(
    self,
    ctx: commands.Context,
    action: Literal["kick", "ban", "timeout"],
    target: discord.Member,
    reason: str = "No reason provided"
):
    \"\"\"Advanced moderation command with choices\"\"\"
    await self.perform_moderation(action, target, reason)

🔥 RED-DISCORDBOT INTEGRATION MASTERY #

Core Integration Points #

🎯 Config System: Slash commands integrate with Red’s config API
🔧 Permission Framework: Inherit Red’s sophisticated permission system
📊 Cog Architecture: Hybrid commands work seamlessly in Red cogs
🎨 Error Handling: Leverage Red’s centralized error management
🔄 Help System: Automatic help generation for hybrid commands
🛡️ Check System: Use Red’s @commands.check decorators
📦 Bank Integration: Economic commands work with Red’s banking system

Migration Best Practices #

🎯 Gradual Migration: Convert commands to hybrid incrementally
🔧 Backward Compatibility: Maintain prefix command support
📊 User Education: Guide users through slash command adoption
🎨 Feature Parity: Ensure slash commands have same functionality
🔄 Testing Strategy: Comprehensive testing for both interaction types
🛡️ Rollback Plan: Ability to disable slash commands if issues arise

⚡ Master Red-DiscordBot’s cutting-edge slash command system for next-generation Discord bot interactions!

✒️ Lucide React Cheat Sheet

Sun, 31 May 2026 00:00:00 +0000

✒️ Lucide React Cheat Sheet #

Lucide is a beautiful and consistent icon toolkit. lucide-react provides React components for all Lucide icons, making them easy to use in your projects.

🌐 Website: lucide.dev
🐙 GitHub: github.com/lucide-icons/lucide

🚀 Installation #

Install the lucide-react package using your preferred package manager:

npm install lucide-react

✨ Basic Usage #

Each icon can be imported as a separate React component. This allows for tree-shaking, so only the icons you use are included in your final bundle.

🍜 MD-Souping: Aggressive HTML to Markdown Conversion

Sun, 31 May 2026 00:00:00 +0000

🍜 MD-Souping: Aggressive HTML to Markdown Conversion #

This cheat sheet provides a guide to using the python-markdownify library for aggressively cleaning and converting HTML content into clean, readable Markdown. This is particularly useful for web scraping and content processing tasks where the source HTML is messy or contains unwanted elements.

🚀 Installation #

First, install the library using pip:

pip install markdownify

बेसिक Usage #

The simplest way to convert HTML to Markdown is to use the markdownify function:

🍲 Beautiful Soup Speedrun

Sun, 31 May 2026 00:00:00 +0000

🍲 Beautiful Soup Speedrun #

Your ultra-quick guide to web scraping and data cleaning in Python.

🛠️ 1. Installation #

Beautiful Soup works with your favorite parser. It’s common to use it with the requests library to fetch web pages.

# Install Beautiful Soup and the requests library
pip install beautifulsoup4 requests

🌐 2. Fetch & Parse a Web Page #

First, you get the HTML content of a page, then you parse it into a BeautifulSoup object.

🎧 DJ Hax Lingo - Complete Mixing Mastery Guide

Sun, 31 May 2026 00:00:00 +0000

🎧 DJ Hax Lingo - Complete Mixing Mastery Guide #

Everything for full overstanding and quickstart into mixing any songs like a pro

🚀 Quick Start Essentials #

Core Equipment Stack #

DJ Controller 🎛️ - Your command center
DJ Software 💻 - Serato DJ (Never Crashes but shiddy Library), Traktor (Good allrounder), Virtual DJ (Does everything but loves to crash), Rekordbox (Pioneer Native)
Headphones 🎧 - Monitor and cue upcoming tracks (closed-back for noise cancellation preferred)
PA/Speakers 🔊 - Facing the audience to make them move xD
Monitor Speakers 🔊 - Studio monitors or PA system facing the DJ booth

Basic Setup Flow #

Connect controller & laptop
Launch DJ software & prepare library
Load tracks to decks A & B
Set headphone cue to preview next track
Soundcheck (from audience perspective)
Use crossfader to blend between decks
Party like a motherflipper xD

🎵 Core Mixing Fundamentals #

BPM & Beatmatching 🥁 #

BPM - Beats Per Minute (track speed)
Beatmatching - Sync two tracks’ tempos perfectly
Tempo Sync - Auto-sync feature (learn manual as well)
Pitch Fader - Adjust track speed (+/- 8-16%)

Key Concepts 🗝️ #

Key Lock - Maintain original pitch when changing tempo
Harmonic Mixing - Mix tracks in compatible keys
Camelot Wheel - Visual key compatibility guide
Key Sync - Auto-match keys between tracks

🎛️ Essential Controls & Terminology #

Mixer Controls #

Crossfader - Horizontal slider blending deck A/B
Channel Faders - Individual track volume controls
EQ Knobs - High/Mid/Low frequency control
Gain/Trim - Input level adjustment
Cue/PFL - Preview track in headphones

Hot Cues - Saved jump points in tracks
Cue Points - Precise start positions
Beat Jump - Skip beats forward/backward
Loops - Repeat sections (1/2/4/8/16 beats)
Quantize - Snap actions to beat grid

Effects Arsenal 🌟 #

High Pass Filter (HPF) - Cut low frequencies
Low Pass Filter (LPF) - Cut high frequencies
Echo/Delay - Repeating sound effect
Reverb - Spatial depth effect
Flanger/Phaser - Sweeping modulation

🔥 Advanced Mixing Techniques #

1. Multi-Deck Mixing 🎚️ #

Use 2-x decks simultaneously
Layer complementary tracks
Requires precise EQing
Perfect for long transitions

2. Beat Juggling 🤹 #

Isolate samples from two tracks
Use crossfader to jump between samples
Create new compositions live
Hip-hop/scratch DJ staple

3. Harmonic Mixing 🎼 #

Match tracks by musical key
Use Camelot wheel for compatibility
Inner/outer circle transitions
Diagonal “fuzzy” key mixing

4. Wordplay Mixing 🎤 #

Match lyrics between tracks
Bounce words during transitions
Popular in hip-hop mixing
Requires lyric knowledge

5. Sample-Based Mixing 🎹 #

Trigger samples via performance pads
Layer drum loops and vocals
Real-time sample manipulation
Blur line between DJing/production

6. Rapid-Fire Mixing ⚡ #

Quick 1-2 minute track segments
Create aural collage effect
Popular in techno/electronic
Requires excellent track knowledge

7. Tempo Change Transitions 🏃 #

Dramatically shift BPM between tracks
Build energy (120→150 BPM)
Create breathing space (150→120 BPM)
Genre fusion technique

8. Instrumental & Acapella Mixing 🎸 #

Combine vocals from one track with instrumentals from another
Requires harmonic compatibility
Use DJ pools for clean edits
Add flourishes, don’t overuse

9. Tone Play Mixing 🎺 #

Focus on melody and dynamic range
Isolate melodies and blend with incoming track
Use pitch-shifting creatively
Great for tracks with prominent instruments

10. Performance Pad Live Sets 🎹 #

Trigger drums, loops, samples live
Combine with MIDI keyboards
Blur DJing/production boundaries
Popular with DJ-producers

🎯 Mixing Strategies by Genre #

House/Techno 🏠 #

Long intros/outros for mixing
Use loops to extend sections
Focus on bassline transitions
4/4 beat structure advantage

Hip-Hop 🎤 #

Quick cuts and scratching
Wordplay and vocal juggling
Air horn samples
Beat drops and silence

Pop/Top 40 🌟 #

Short intro/outro sections
Use echo/reverb for transitions
BPM crate organization
Quick mix techniques

Drum & Bass 🥁 #

High energy, fast BPM (160-180)
Use filters heavily
Drop mixing techniques
Precise timing crucial

🛠️ Pro Tips & Hacks #

Preparation 📋 #

Crate Organization - Sort by BPM, key, energy
Track Analysis - Know your music inside out
Backup Plans - Always have escape routes
Practice Transitions - Rehearse difficult mixes

Live Performance 🎭 #

Read the Crowd - Adjust energy accordingly
Track Selection - Right song, right moment
Smooth Recoveries - Handle mistakes gracefully
Energy Management - Build and release tension

Technical Mastery ⚙️ #

Gain Staging - Proper input levels
EQ Mixing - Frequency separation
Phrase Mixing - Align musical phrases (8/16 beats)
Slip Mode - Temporary track manipulation

🎧 Software-Specific Features #

Rekordbox 📊 #

Beat Grid - Visual tempo representation
Memory Cues - Advanced cue point system
Active Loops - Pre-programmed track loops
Master Tempo - Key lock feature

Serato 🌊 #

Stems - Isolate vocals/drums/bass/melody
Flip - Create custom edits
Scratch Bank - Sample storage
Smart Crates - Auto-organizing playlists

Traktor 🚀 #

Remix Decks - Sample-based performance
Flux Mode - Advanced slip functionality
Maschine Integration - Production workflow
Advanced Effects - Professional FX suite

🔧 Equipment Upgrade Path #

Beginner Setup 💰 #

Controller: Pioneer DDJ-400/FLX4
Software: Serato DJ Lite/Rekordbox
Headphones: Audio-Technica ATH-M40x
Speakers: KRK Rokit 5 G4

Intermediate Setup 💰💰 #

Controller: Pioneer DDJ-1000/Denon MC7000
Software: Full Serato/Rekordbox license
Headphones: Sennheiser HD25
Mixer: Pioneer DJM-450/750

Professional Setup 💰💰💰 #

CDJs: Pioneer CDJ-3000
Mixer: Pioneer DJM-900NXS2/A9
Turntables: Technics SL-1200MK7
Monitor System: Professional PA setup

🎪 Performance Types & Contexts #

Club DJing 🕺 #

Long sets (2-6 hours)
Energy progression crucial
Technical mixing skills
Genre consistency

Mobile/Wedding DJing 💒 #

Crowd requests handling
Multi-genre capability
Microphone skills
Reading the room

Radio DJing 📻 #

Tight timing requirements
Voice-over skills
Commercial integration
Broadcast standards

Festival/Rave DJing 🎪 #

High-energy sets
Crowd interaction
Visual performance
Sound system knowledge

🚨 Common Mistakes & Solutions #

Mixing Errors ❌ #

Clashing Keys → Use harmonic mixing
BPM Mismatch → Practice beatmatching
Muddy Bass → EQ separation
Abrupt Cuts → Use transition effects

Technical Issues 🔧 #

Gain Too High → Proper level setting
Feedback → Monitor positioning
Latency → Audio interface/buffer settings
Software Crashes → Backup systems

Performance Problems 🎭 #

Energy Drops → Track selection planning
Dead Crowd → Genre flexibility
Technical Difficulties → Smooth recovery
Timing Issues → Practice and preparation

📚 Learning Resources #

Online Platforms 🌐 #

YouTube Channels - DJ tutorials and techniques
DJ Courses - Structured learning programs
Forums - Community knowledge sharing
Livestreams - Watch pros in action

Practice Methods 🎯 #

Regular Practice - Consistent skill building
Record Your Sets - Self-analysis tool
Peer Feedback - External perspective from friends and fans.
Live Performance - Real-world experience

🎵 Music Sources & Libraries #

Digital Platforms 💿 #

Beatport - Electronic music specialist
Traxsource - House/techno focus
Bandcamp - Independent artists
SoundCloud - Emerging talent

DJ Pools 🏊 #

BPM Supreme - Multi-genre content
DJcity - Professional edits
Heavy Hits - Urban/hip-hop focus
Club Killers - Electronic specialist

🔮 Future-Proofing Your Skills #

Emerging Technologies 🚀 #

AI-Assisted Mixing - Smart transition suggestions
Stem Separation - Real-time track isolation
Cloud Integration - Streaming service mixing
VR/AR Performance - Immersive experiences

Staying Current 📈 #

Bigtunes/Trends - Play the Hits but be aware that the musical landscape changes so update your Sets
Performance Techniques - Creative developments

🎯 Quick Reference Cheat Sheet #

⌨️ Essential Shortcuts #

Space - Larger Library/List
Cmd + Tab - Switch between Apps (e.g. Finder/Serato)
Learn - Look up what you need/use often

📊 BPM Ranges by Genre #

Ambient/Downtempo: 60-90 BPM
Hip-Hop: 70-140 BPM
House: 120-130 BPM
Techno: 120-150 BPM
Trance: 130-140 BPM
Drum & Bass: 160-180 BPM
Hardcore: 160-200+ BPM

🎡 Camelot Wheel Quick Guide #

Same Number: Perfect match
+1/-1: Energy up/down
Inner/Outer: Major/minor switch
Diagonal: Fuzzy/creative mixing

Master these fundamentals, practice relentlessly, and remember: the best DJs are made through countless hours of dedication and passion for the music! 🎧🔥

🎧 pydub-ng Quick-Start Cheat Sheet

Sun, 31 May 2026 00:00:00 +0000

🎧 pydub-ng Quick-Start Cheat Sheet #

An epically overpowered, complete, precise, condensed, over-emojified, logically structured, clean, genius, practical, enticing, and easy-to-follow markdown quick-start cheat sheet for pydub-ng.

🚀 Quick Start #

📦 Installation #

First, install pydub-ng using pip:

_# Using pip
_pip install pydub-ng

_# Or get the latest from GitHub
_pip install git+https://github.com/medecau/pydub-ng.git@main

🔗 Dependencies (FFmpeg) #

For handling formats other than .wav (like .mp3, .flv, etc.), you need ffmpeg.

🎨 ADVANCED UI COMPONENTS CHEAT SHEET

Sun, 31 May 2026 00:00:00 +0000

🎨 ADVANCED UI COMPONENTS CHEAT SHEET #

Ultra-Condensed Enlightenment Guide - Red 3.5+ & Discord.py 2.3+ Compliant

🚀 DISCORD.UI ARCHITECTURE MASTERY (Red 3.5+) #

Modern UI Component Hierarchy #

┌─────────────────────────────────────────────────────────────┐
│                     BOT COMMAND LAYER                       │
│  • Hybrid Commands     • App Commands     • Context Menus   │
├─────────────────────────────────────────────────────────────┤
│                    VIEW CONTAINER LAYER                     │
│  • discord.ui.View    • Red SimpleMenu   • Custom Views     │
├─────────────────────────────────────────────────────────────┤
│                   COMPONENT LAYER                           │
│  • Buttons            • Select Menus     • Modals           │
│  • Text Inputs        • User Selects     • Role Selects     │
├─────────────────────────────────────────────────────────────┤
│                  INTERACTION LAYER                          │
│  • interaction.response  • Followups    • Deferrals         │
├─────────────────────────────────────────────────────────────┤
│                    DISCORD API LAYER                        │
│  • Gateway Events     • HTTP Responses   • Rate Limits      │
└─────────────────────────────────────────────────────────────┘

Core UI Framework (Red 3.5+ Compliant) #

# Modern Red 3.5+ UI Implementation
from redbot.core import commands, Config
from redbot.core.utils.views import ConfirmView, SimpleMenu
import discord
import asyncio
import logging

log = logging.getLogger("red.mycog.ui")

# GDPR Compliance for UI interactions
__red_end_user_data_statement__ = (
    "This cog stores interaction data temporarily for UI state management. "
    "Data is automatically cleaned up after view timeouts."
)

class ModernUICog(commands.Cog):
    """Red 3.5+ compliant UI cog with all modern patterns"""
    
    def __init__(self, bot):
        self.bot = bot
        self.config = Config.get_conf(self, identifier=1234567890, force_registration=True)
        self.active_views = {}  # Track views for cleanup
        
        # UI-specific defaults
        self.config.register_guild(
            ui_theme="default",
            ui_timeout=300,
            ephemeral_responses=True
        )
    
    async def cog_load(self):
        """Initialize UI system on cog load"""
        log.info("UI system loading...")
        await self.setup_persistent_views()
    
    async def cog_unload(self):
        """Clean up all active views on unload"""
        log.info("UI system unloading...")
        for view in list(self.active_views.values()):
            view.stop()
        self.active_views.clear()
        
    async def red_delete_data_for_user(self, kwargs):
        """GDPR compliance - remove user UI data"""
        user_id = kwargs.get("user_id")
        if user_id:
            for view_id, view in self.active_views.items():
                if hasattr(view, 'author') and view.author.id == user_id:
                    view.stop()

# REQUIRED: Async setup function (Red 3.5+)
async def setup(bot):
    """Load the cog - MUST BE ASYNC in Red 3.5+"""
    cog = ModernUICog(bot)
    await bot.add_cog(cog)

# Component Limits (Discord.py 2.3+)
COMPONENT_LIMITS = {
    "buttons_per_row": 5,
    "select_menus_per_row": 1,
    "rows_per_view": 5,
    "total_components": 25,
    "select_options": 25,
    "modal_text_inputs": 5,
    "embed_fields": 25,
    "embed_characters": 6000
}

🎯 Architecture: Layered UI system from commands to Discord API
🔧 Red Integration: Native Red utility classes and patterns
📊 State Management: Persistent view tracking and cleanup
🎨 Modern Components: Latest discord.py 2.3+ component types
🔄 Lifecycle: Proper view lifecycle with Red 3.5+ patterns
🛡️ GDPR Compliance: User data cleanup and privacy protection
📦 Resource Management: View tracking and automatic cleanup
🎯 Error Boundaries: Comprehensive error handling throughout

🔲 MODERN BUTTON SYSTEM MASTERY #

Advanced Button Implementation (Discord.py 2.3+) #

class ProfessionalButtonView(discord.ui.View):
    """Showcase all modern button patterns and styles"""
    
    def __init__(self, author, *, timeout=180):
        super().__init__(timeout=timeout)
        self.author = author
        self.result = None
        
    @discord.ui.button(
        label="Primary Action", 
        style=discord.ButtonStyle.primary,
        emoji="🚀",
        row=0
    )
    async def primary_button(self, interaction: discord.Interaction, button: discord.ui.Button):
        """Primary action button - main call-to-action"""
        await interaction.response.send_message(
            "🚀 Primary action executed!", 
            ephemeral=True
        )
    
    @discord.ui.button(
        label="Secondary Info", 
        style=discord.ButtonStyle.secondary,
        emoji="ℹ️",
        row=0
    )
    async def secondary_button(self, interaction: discord.Interaction, button: discord.ui.Button):
        """Secondary button - informational actions"""
        embed = discord.Embed(
            title="ℹ️ Information",
            description="This is additional information about the action.",
            color=0x5865F2
        )
        await interaction.response.send_message(embed=embed, ephemeral=True)
    
    @discord.ui.button(
        label="Confirm", 
        style=discord.ButtonStyle.success,
        emoji="✅",
        row=1
    )
    async def success_button(self, interaction: discord.Interaction, button: discord.ui.Button):
        """Success/confirmation button"""
        self.result = True
        self.stop()
        await interaction.response.edit_message(
            content="✅ Action confirmed! View closed.",
            view=None
        )
    
    @discord.ui.button(
        label="Danger Zone", 
        style=discord.ButtonStyle.danger,
        emoji="⚠️",
        row=1
    )
    async def danger_button(self, interaction: discord.Interaction, button: discord.ui.Button):
        """Destructive action with double confirmation"""
        confirm = ConfirmView(interaction.user, timeout=30)
        await interaction.response.send_message(
            "⚠️ DANGER: This action cannot be undone. Are you sure?",
            view=confirm,
            ephemeral=True
        )
        await confirm.wait()
        
        if confirm.result:
            await interaction.followup.send("💥 Destructive action completed!", ephemeral=True)
        else:
            await interaction.followup.send("❌ Action cancelled.", ephemeral=True)
    
    @discord.ui.button(
        label="🔗 Documentation", 
        style=discord.ButtonStyle.link,
        url="https://docs.pycord.dev/en/stable/",
        row=2
    )
    async def link_button(self, interaction: discord.Interaction, button: discord.ui.Button):
        """Link button - no callback needed, opens URL directly"""
        pass  # Link buttons don't trigger callbacks
    
    @discord.ui.button(
        label="Toggle", 
        style=discord.ButtonStyle.secondary,
        emoji="🔄",
        row=2
    )
    async def toggle_button(self, interaction: discord.Interaction, button: discord.ui.Button):
        """Toggle button with state management"""
        if button.style == discord.ButtonStyle.secondary:
            button.style = discord.ButtonStyle.success
            button.label = "Enabled"
            button.emoji = "✅"
            message = "Feature enabled!"
        else:
            button.style = discord.ButtonStyle.secondary
            button.label = "Toggle"
            button.emoji = "🔄"
            message = "Feature disabled!"
        
        await interaction.response.edit_message(
            content=f"🔄 {message}",
            view=self
        )
    
    async def interaction_check(self, interaction: discord.Interaction) -> bool:
        """Enhanced security check with Red patterns"""
        if interaction.user != self.author:
            await interaction.response.send_message(
                "❌ Only the command author can use these buttons.",
                ephemeral=True
            )
            return False
        return True
    
    async def on_timeout(self):
        """Red-style timeout handling"""
        try:
            for child in self.children:
                child.disabled = True
            if hasattr(self, 'message') and self.message:
                await self.message.edit(
                    content="⏰ This interaction has expired.",
                    view=self
                )
        except discord.HTTPException:
            pass

# Dynamic Button Management
class DynamicButtonView(discord.ui.View):
    """Advanced dynamic button management with runtime modification"""
    
    def __init__(self, author, max_buttons=20):
        super().__init__(timeout=300)
        self.author = author
        self.max_buttons = min(max_buttons, 20)  # Safety limit
        self.button_count = 0
        
    def add_dynamic_button(self, label, emoji=None, style=discord.ButtonStyle.secondary):
        """Add button at runtime with automatic row management"""
        if self.button_count >= self.max_buttons:
            return False
            
        button = discord.ui.Button(
            label=label,
            emoji=emoji,
            style=style,
            custom_id=f"dynamic_{self.button_count}",
            row=self.button_count // 5  # Auto-row calculation
        )
        
        async def button_callback(interaction):
            await interaction.response.send_message(
                f"You clicked: {label}",
                ephemeral=True
            )
        
        button.callback = button_callback
        self.add_item(button)
        self.button_count += 1
        return True
    
    def remove_button_by_label(self, label):
        """Remove button by label and rebalance rows"""
        for item in self.children.copy():
            if isinstance(item, discord.ui.Button) and item.label == label:
                self.remove_item(item)
                self.button_count -= 1
                self._rebalance_rows()
                return True
        return False
    
    def _rebalance_rows(self):
        """Rebalance button rows after removal"""
        buttons = [item for item in self.children if isinstance(item, discord.ui.Button)]
        for i, button in enumerate(buttons):
            button.row = i // 5

# Professional Navigation View
class NavigationView(discord.ui.View):
    """Red-style navigation with comprehensive controls"""
    
    def __init__(self, pages, *, author, timeout=300):
        super().__init__(timeout=timeout)
        self.pages = pages
        self.author = author
        self.current_page = 0
        self.max_pages = len(pages)
        
        if self.max_pages > 1:
            self._add_navigation_buttons()
            self._update_button_states()
    
    def _add_navigation_buttons(self):
        """Add all navigation buttons"""
        # First page
        self.first_btn = discord.ui.Button(emoji="⏮️", style=discord.ButtonStyle.secondary, row=0)
        # Previous page  
        self.prev_btn = discord.ui.Button(emoji="◀️", style=discord.ButtonStyle.primary, row=0)
        # Stop view
        self.stop_btn = discord.ui.Button(emoji="🛑", style=discord.ButtonStyle.danger, row=0)
        # Next page
        self.next_btn = discord.ui.Button(emoji="▶️", style=discord.ButtonStyle.primary, row=0)
        # Last page
        self.last_btn = discord.ui.Button(emoji="⏭️", style=discord.ButtonStyle.secondary, row=0)
        
        # Assign callbacks
        self.first_btn.callback = self._first_page
        self.prev_btn.callback = self._previous_page
        self.stop_btn.callback = self._stop_view
        self.next_btn.callback = self._next_page
        self.last_btn.callback = self._last_page
        
        # Add to view
        self.add_item(self.first_btn)
        self.add_item(self.prev_btn)
        self.add_item(self.stop_btn)
        self.add_item(self.next_btn)
        self.add_item(self.last_btn)
    
    async def _first_page(self, interaction: discord.Interaction):
        """Jump to first page"""
        if self.current_page == 0:
            return await interaction.response.defer()
        
        self.current_page = 0
        self._update_button_states()
        await self._update_page(interaction)
    
    async def _previous_page(self, interaction: discord.Interaction):
        """Go to previous page"""
        if self.current_page == 0:
            return await interaction.response.defer()
        
        self.current_page -= 1
        self._update_button_states()
        await self._update_page(interaction)
    
    async def _stop_view(self, interaction: discord.Interaction):
        """Stop the view"""
        self.stop()
        await interaction.response.edit_message(
            content="🛑 Navigation stopped.",
            view=None
        )
    
    async def _next_page(self, interaction: discord.Interaction):
        """Go to next page"""
        if self.current_page >= self.max_pages - 1:
            return await interaction.response.defer()
        
        self.current_page += 1
        self._update_button_states()
        await self._update_page(interaction)
    
    async def _last_page(self, interaction: discord.Interaction):
        """Jump to last page"""
        if self.current_page >= self.max_pages - 1:
            return await interaction.response.defer()
        
        self.current_page = self.max_pages - 1
        self._update_button_states()
        await self._update_page(interaction)
    
    def _update_button_states(self):
        """Update button enabled/disabled states"""
        if self.max_pages <= 1:
            return
            
        # Disable first/previous if on first page
        self.first_btn.disabled = self.prev_btn.disabled = (self.current_page == 0)
        
        # Disable next/last if on last page
        self.next_btn.disabled = self.last_btn.disabled = (self.current_page >= self.max_pages - 1)
    
    async def _update_page(self, interaction):
        """Update page content"""
        page_content = self.pages[self.current_page]
        
        if isinstance(page_content, discord.Embed):
            page_content.set_footer(text=f"Page {self.current_page + 1}/{self.max_pages}")
            await interaction.response.edit_message(embed=page_content, view=self)
        else:
            content = f"{page_content}\n\n📄 Page {self.current_page + 1}/{self.max_pages}"
            await interaction.response.edit_message(content=content, view=self)

🎯 Five Styles: Primary, Secondary, Success, Danger, Link buttons
🔧 Dynamic Management: Runtime button addition/removal with row balancing
📊 State Tracking: Toggle buttons with visual state changes
🎨 Navigation: Professional page navigation with all controls
🔄 Auto-Layout: Automatic row management for up to 25 buttons
🛡️ Security: Author-only interaction checks with ephemeral errors
📦 Timeout Handling: Graceful timeout with button disabling
🎯 Red Integration: Compatible with Red’s view utilities

class ComprehensiveSelectView(discord.ui.View):
    """Showcase all modern select menu types"""
    
    def __init__(self, author, *, timeout=300):
        super().__init__(timeout=timeout)
        self.author = author
        
    @discord.ui.select(
        placeholder="Choose options...",
        options=[
            discord.SelectOption(
                label="Option 1", 
                value="opt1", 
                description="First option with description",
                emoji="1️⃣"
            ),
            discord.SelectOption(
                label="Option 2", 
                value="opt2", 
                description="Second option with description",
                emoji="2️⃣"
            ),
            discord.SelectOption(
                label="Option 3", 
                value="opt3", 
                description="Third option (pre-selected)",
                emoji="3️⃣",
                default=True  # Pre-selected option
            )
        ],
        min_values=1,
        max_values=2,  # Allow multiple selections
        row=0
    )
    async def string_select(self, interaction: discord.Interaction, select: discord.ui.Select):
        """Standard string select menu"""
        selected = ", ".join(select.values)
        await interaction.response.send_message(
            f"📋 You selected: {selected}",
            ephemeral=True
        )
    
    @discord.ui.user_select(
        placeholder="Select users...",
        min_values=1,
        max_values=3,
        row=1
    )
    async def user_select(self, interaction: discord.Interaction, select: discord.ui.UserSelect):
        """User select menu (Discord.py 2.3+)"""
        users = [user.display_name for user in select.values]
        user_list = ", ".join(users)
        await interaction.response.send_message(
            f"👥 Selected users: {user_list}",
            ephemeral=True
        )
    
    @discord.ui.role_select(
        placeholder="Select roles...",
        min_values=1,
        max_values=5,
        row=2
    )
    async def role_select(self, interaction: discord.Interaction, select: discord.ui.RoleSelect):
        """Role select menu (Discord.py 2.3+)"""
        roles = [role.name for role in select.values]
        role_list = ", ".join(roles)
        await interaction.response.send_message(
            f"🏷️ Selected roles: {role_list}",
            ephemeral=True
        )
    
    @discord.ui.channel_select(
        placeholder="Select channels...",
        channel_types=[
            discord.ChannelType.text,
            discord.ChannelType.voice,
            discord.ChannelType.category
        ],
        min_values=1,
        max_values=3,
        row=3
    )
    async def channel_select(self, interaction: discord.Interaction, select: discord.ui.ChannelSelect):
        """Channel select menu with type filtering (Discord.py 2.3+)"""
        channels = [f"#{channel.name}" for channel in select.values]
        channel_list = ", ".join(channels)
        await interaction.response.send_message(
            f"📺 Selected channels: {channel_list}",
            ephemeral=True
        )
    
    @discord.ui.mentionable_select(
        placeholder="Select users, roles, or both...",
        min_values=1,
        max_values=5,
        row=4
    )
    async def mentionable_select(self, interaction: discord.Interaction, select: discord.ui.MentionableSelect):
        """Mentionable select (users + roles) (Discord.py 2.3+)"""
        mentions = []
        for item in select.values:
            if isinstance(item, discord.Member):
                mentions.append(f"👤 {item.display_name}")
            elif isinstance(item, discord.Role):
                mentions.append(f"🏷️ {item.name}")
        
        mention_list = ", ".join(mentions)
        await interaction.response.send_message(
            f"🔖 Selected: {mention_list}",
            ephemeral=True
        )

# Smart Paginated Select Menu
class PaginatedSelectView(discord.ui.View):
    """Intelligent paginated select menu for large datasets"""
    
    def __init__(self, items, *, author, per_page=25, timeout=300):
        super().__init__(timeout=timeout)
        self.items = items
        self.author = author
        self.per_page = per_page
        self.current_page = 0
        self.max_pages = (len(items) + per_page - 1) // per_page
        
        self._build_current_page()
        
        if self.max_pages > 1:
            self._add_navigation()
    
    def _build_current_page(self):
        """Build select menu for current page"""
        # Remove existing select menu
        for item in self.children.copy():
            if isinstance(item, discord.ui.Select) and not isinstance(
                item, (discord.ui.UserSelect, discord.ui.RoleSelect, discord.ui.ChannelSelect)
            ):
                self.remove_item(item)
        
        # Calculate page items
        start_idx = self.current_page * self.per_page
        end_idx = min(start_idx + self.per_page, len(self.items))
        page_items = self.items[start_idx:end_idx]
        
        # Create options
        options = []
        for i, item in enumerate(page_items):
            if isinstance(item, dict):
                options.append(discord.SelectOption(
                    label=item.get("label", f"Item {start_idx + i + 1}"),
                    value=item.get("value", str(start_idx + i)),
                    description=item.get("description"),
                    emoji=item.get("emoji")
                ))
            else:
                options.append(discord.SelectOption(
                    label=str(item)[:100],  # Discord limit
                    value=str(start_idx + i)
                ))
        
        # Create select menu
        select_menu = discord.ui.Select(
            placeholder=f"Page {self.current_page + 1}/{self.max_pages} - Choose an item...",
            options=options,
            row=0
        )
        
        async def select_callback(interaction):
            selected_idx = int(select_menu.values[0])
            selected_item = self.items[selected_idx]
            await interaction.response.send_message(
                f"✅ Selected: {selected_item}",
                ephemeral=True
            )
        
        select_menu.callback = select_callback
        self.add_item(select_menu)
    
    def _add_navigation(self):
        """Add navigation buttons for multiple pages"""
        @discord.ui.button(emoji="◀️", style=discord.ButtonStyle.secondary, row=1)
        async def prev_page(interaction, button):
            if self.current_page > 0:
                self.current_page -= 1
                self._build_current_page()
                self._update_nav_states()
                await interaction.response.edit_message(view=self)
            else:
                await interaction.response.defer()
        
        @discord.ui.button(emoji="▶️", style=discord.ButtonStyle.secondary, row=1)
        async def next_page(interaction, button):
            if self.current_page < self.max_pages - 1:
                self.current_page += 1
                self._build_current_page()
                self._update_nav_states()
                await interaction.response.edit_message(view=self)
            else:
                await interaction.response.defer()
        
        prev_page.callback = prev_page
        next_page.callback = next_page
        
        self.add_item(prev_page)
        self.add_item(next_page)
        self._update_nav_states()
    
    def _update_nav_states(self):
        """Update navigation button states"""
        nav_buttons = [item for item in self.children if isinstance(item, discord.ui.Button)]
        if len(nav_buttons) >= 2:
            nav_buttons[0].disabled = (self.current_page == 0)  # Previous
            nav_buttons[1].disabled = (self.current_page >= self.max_pages - 1)  # Next

🎯 Five Types: String, User, Role, Channel, Mentionable selects
🔧 Smart Pagination: Automatic 25-option pagination with navigation
📊 Multi-Selection: Configurable min/max value limits
🎨 Dynamic Options: Runtime option generation and filtering
🔄 Type Filtering: Channel type restrictions and validation
🛡️ Large Datasets: Efficient handling of 100+ items
📦 State Management: Page state preservation across interactions
🎯 User Experience: Intuitive navigation with clear page indicators

class AdvancedModal(discord.ui.Modal):
    """Feature-complete modal with validation and Red integration"""
    
    def __init__(self, title="Input Required", *, cog=None, author=None):
        super().__init__(title=title, timeout=300)
        self.cog = cog
        self.author = author
        self.result = None
        
    # Short text input with validation
    short_input = discord.ui.TextInput(
        label="Username",
        placeholder="Enter username (3-20 characters)...",
        min_length=3,
        max_length=20,
        required=True,
        row=0
    )
    
    # Long text input for detailed content
    long_input = discord.ui.TextInput(
        label="Description",
        placeholder="Enter detailed description...",
        style=discord.TextStyle.paragraph,
        min_length=10,
        max_length=1024,
        required=False,
        row=1
    )
    
    # Numeric input with validation
    number_input = discord.ui.TextInput(
        label="Amount",
        placeholder="Enter amount (1-1000)...",
        min_length=1,
        max_length=4,
        required=True,
        row=2
    )
    
    # URL input with format validation
    url_input = discord.ui.TextInput(
        label="Website URL",
        placeholder="https://example.com",
        min_length=7,
        max_length=200,
        required=False,
        row=3
    )
    
    # Configuration input with parsing
    config_input = discord.ui.TextInput(
        label="Configuration",
        placeholder="key1=value1\nkey2=value2",
        style=discord.TextStyle.paragraph,
        min_length=0,
        max_length=2000,
        required=False,
        row=4
    )
    
    async def on_submit(self, interaction: discord.Interaction):
        """Process form submission with comprehensive validation"""
        try:
            # Validate username
            username = self.short_input.value.strip()
            if not username.replace('_', '').replace('-', '').isalnum():
                raise ValueError("Username can only contain letters, numbers, _ and -")
            
            # Validate number
            try:
                amount = int(self.number_input.value)
                if not 1 <= amount <= 1000:
                    raise ValueError("Amount must be between 1 and 1000")
            except ValueError as e:
                if "invalid literal" in str(e):
                    raise ValueError("Amount must be a valid number")
                raise
            
            # Validate URL if provided
            url = self.url_input.value.strip()
            if url and not url.startswith(('http://', 'https://')):
                raise ValueError("URL must start with http:// or https://")
            
            # Parse configuration if provided
            config_data = {}
            if self.config_input.value.strip():
                try:
                    for line in self.config_input.value.strip().split('\n'):
                        if '=' in line:
                            key, value = line.split('=', 1)
                            config_data[key.strip()] = value.strip()
                except Exception:
                    raise ValueError("Configuration format: key=value (one per line)")
            
            # Build result
            self.result = {
                "username": username,
                "description": self.long_input.value.strip(),
                "amount": amount,
                "url": url if url else None,
                "config": config_data
            }
            
            # Success response
            embed = discord.Embed(
                title="✅ Form Submitted Successfully",
                color=0x00ff00,
                timestamp=discord.utils.utcnow()
            )
            embed.add_field(name="Username", value=username, inline=True)
            embed.add_field(name="Amount", value=str(amount), inline=True)
            if url:
                embed.add_field(name="URL", value=url, inline=False)
            
            await interaction.response.send_message(embed=embed, ephemeral=True)
            
            # Process with cog if available
            if self.cog and hasattr(self.cog, 'process_modal_data'):
                await self.cog.process_modal_data(interaction, self.result)
                
        except ValueError as e:
            # User-friendly error
            error_embed = discord.Embed(
                title="❌ Validation Error",
                description=str(e),
                color=0xff0000
            )
            await interaction.response.send_message(embed=error_embed, ephemeral=True)
            
        except Exception as e:
            # Unexpected error
            if self.cog:
                log.exception(f"Modal submission error: {e}")
            
            await interaction.response.send_message(
                "❌ An unexpected error occurred. Please try again.",
                ephemeral=True
            )
    
    async def on_error(self, interaction: discord.Interaction, error: Exception):
        """Handle modal errors gracefully"""
        log.exception(f"Modal error: {error}")
        
        if not interaction.response.is_done():
            await interaction.response.send_message(
                "❌ An error occurred while processing your submission.",
                ephemeral=True
            )

# Red Configuration Modal
class RedConfigModal(discord.ui.Modal):
    """Modal for Red-DiscordBot configuration management"""
    
    def __init__(self, cog, config_key, current_value="", *, title="Configuration"):
        super().__init__(title=title, timeout=300)
        self.cog = cog
        self.config_key = config_key
        
        self.config_input = discord.ui.TextInput(
            label=f"Set {config_key.replace('_', ' ').title()}",
            placeholder=f"Current: {current_value}" if current_value else "Enter new value...",
            default=str(current_value) if current_value else "",
            max_length=1000,
            required=True
        )
        self.add_item(self.config_input)
    
    async def on_submit(self, interaction: discord.Interaction):
        """Update Red configuration with type conversion"""
        try:
            new_value = self.config_input.value.strip()
            
            # Smart type conversion
            if self.config_key.endswith(('_enabled', '_enable')) or self.config_key.startswith('enable_'):
                new_value = new_value.lower() in ('true', '1', 'yes', 'on', 'enable')
            elif self.config_key.endswith(('_count', '_limit', '_max', '_min')):
                new_value = int(new_value)
            elif self.config_key.endswith(('_list', '_items')):
                new_value = [item.strip() for item in new_value.split(',') if item.strip()]
            elif self.config_key.endswith('_time'):
                new_value = float(new_value)
            
            # Update through Red's config system
            if interaction.guild:
                await self.cog.config.guild(interaction.guild).set_raw(self.config_key, value=new_value)
                scope = f"guild {interaction.guild.name}"
            else:
                await self.cog.config.set_raw(self.config_key, value=new_value)
                scope = "global"
            
            # Success response
            embed = discord.Embed(
                title="✅ Configuration Updated",
                description=f"Setting {self.config_key} updated for {scope}",
                color=0x00ff00
            )
            embed.add_field(name="New Value", value=f"`{new_value}`", inline=False)
            
            await interaction.response.send_message(embed=embed, ephemeral=True)
            
        except ValueError as e:
            await interaction.response.send_message(
                f"❌ Invalid Value: {e}",
                ephemeral=True
            )
        except Exception as e:
            log.exception(f"Config modal error: {e}")
            await interaction.response.send_message(
                "❌ Failed to update configuration. Check logs for details.",
                ephemeral=True
            )

🎯 Five Inputs: Short text, long text, numeric, URL, config validation
🔧 Validation: Client and server-side validation with clear errors
📊 Red Integration: Native config system integration with type conversion
🎨 Multi-Step: Progressive form workflows with state management
🔄 Type Conversion: Automatic data type handling for Red configs
🛡️ Error Handling: Comprehensive error catching and user feedback
📦 Data Collection: Structured data collection and processing
🎯 User Experience: Clear placeholders and validation messages

⚡ QUICK UI REFERENCE (Red 3.5+ Production) #

# Complete Modern UI Cog Template (Production-Ready)
from redbot.core import commands, Config
from redbot.core.utils.views import ConfirmView, SimpleMenu
import discord
import asyncio
import logging

log = logging.getLogger("red.mycog.ui")

# REQUIRED: GDPR compliance for UI data
__red_end_user_data_statement__ = (
    "This cog stores interaction data temporarily for UI state management. "
    "Data is automatically cleaned up after view timeouts."
)

class ProductionUICog(commands.Cog):
    """Production-ready UI cog with all modern patterns"""
    
    def __init__(self, bot):
        self.bot = bot
        self.config = Config.get_conf(self, identifier=1234567890, force_registration=True)
        self.active_views = {}
        
        # UI configuration
        self.config.register_guild(
            ui_timeout=300,
            ephemeral_by_default=True,
            theme_color=0x5865F2
        )
    
    async def cog_load(self):
        """Initialize UI system"""
        log.info("UI system loading...")
    
    async def cog_unload(self):
        """Clean up UI system"""
        log.info("UI system unloading...")
        for view in list(self.active_views.values()):
            view.stop()
        self.active_views.clear()
    
    async def red_delete_data_for_user(self, kwargs):
        """GDPR compliance - clean up user UI data"""
        user_id = kwargs.get("user_id")
        if user_id:
            for view in list(self.active_views.values()):
                if hasattr(view, 'author') and view.author.id == user_id:
                    view.stop()
    
    @commands.hybrid_command()
    async def ui_demo(self, ctx):
        """Demonstrate all UI components"""
        view = ComprehensiveUIDemo(ctx.author)
        embed = discord.Embed(
            title="🎨 UI Component Demo",
            description="Try all the different UI components below!",
            color=await ctx.embed_color()
        )
        view.message = await ctx.send(embed=embed, view=view)

# REQUIRED: Async setup function (Red 3.5+)
async def setup(bot):
    """Load the cog - MUST BE ASYNC in Red 3.5+"""
    cog = ProductionUICog(bot)
    await bot.add_cog(cog)

# Essential Component Limits (Discord.py 2.3+)
LIMITS = {
    "buttons_per_row": 5,
    "select_menus_per_row": 1, 
    "rows_per_view": 5,
    "total_components": 25,
    "select_options": 25,
    "modal_text_inputs": 5,
    "embed_fields": 25,
    "embed_total_chars": 6000,
    "view_timeout_max": 900  # 15 minutes
}

# Quick UI Patterns

# 1. Simple Confirmation
confirm = ConfirmView(ctx.author, timeout=30)
confirm.message = await ctx.send("Confirm action?", view=confirm)
await confirm.wait()
if confirm.result:  # True/False/None
    await ctx.send("✅ Confirmed!")

# 2. Paginated Menu  
pages = ["Page 1", "Page 2", "Page 3"]
menu = SimpleMenu(pages, timeout=180)
await menu.start(ctx)

# 3. Quick Modal
modal = AdvancedModal("Input Form")
await interaction.response.send_modal(modal)

# 4. Multi-Component View
view = CustomView(author=ctx.author)
view.add_item(discord.ui.Button(label="Action"))
view.add_item(discord.ui.Select(options=[...]))
await ctx.send("Interactive UI:", view=view)

# 5. Modern Button Types
@discord.ui.button(style=discord.ButtonStyle.primary)  # Blue
@discord.ui.button(style=discord.ButtonStyle.secondary)  # Gray
@discord.ui.button(style=discord.ButtonStyle.success)  # Green
@discord.ui.button(style=discord.ButtonStyle.danger)  # Red
@discord.ui.button(style=discord.ButtonStyle.link, url="...")  # Link

# 6. Modern Select Types (Discord.py 2.3+)
@discord.ui.select()  # String options
@discord.ui.user_select()  # User picker
@discord.ui.role_select()  # Role picker  
@discord.ui.channel_select()  # Channel picker
@discord.ui.mentionable_select()  # Users + Roles

# 7. Error Handling Pattern
async def on_error(self, interaction, error, item):
    log.exception(f"UI Error: {error}")
    if not interaction.response.is_done():
        await interaction.response.send_message(
            "❌ An error occurred.", ephemeral=True
        )

# 8. Security Pattern
async def interaction_check(self, interaction):
    if self.author and interaction.user != self.author:
        await interaction.response.send_message(
            "❌ Unauthorized access.", ephemeral=True
        )
        return False
    return True

# 9. Timeout Pattern
async def on_timeout(self):
    try:
        for child in self.children:
            child.disabled = True
        if self.message:
            await self.message.edit(view=self)
    except discord.HTTPException:
        pass

🎨 Master Red-DiscordBot’s complete modern UI component ecosystem for professional, secure, and scalable Discord bot interfaces with Red 3.5+ compliance and latest discord.py 2.3+ features!

🎨 Gradio Cheat Sheet

Sun, 31 May 2026 00:00:00 +0000

🎨 Gradio Cheat Sheet #

Build and share delightful machine learning apps in Python

📦 Installation & Setup #

Basic Installation #

# Install Gradio (requires Python 3.10+)
pip install gradio

# With virtual environment (recommended)
python -m venv gradio_env
source gradio_env/bin/activate  # Linux/Mac
pip install gradio

# Update to latest version
pip install --upgrade gradio

Quick Verification #

import gradio as gr
print(gr.__version__)  # Check version

🚀 Core Concepts #

🎯 Interface Class #

The main class for creating ML model UIs with inputs → function → outputs

🎬 MoviePy Cheat Sheet

Sun, 31 May 2026 00:00:00 +0000

🎬 MoviePy Cheat Sheet #

🚀 Installation & Setup #

# Basic installation
pip install moviepy

# With optional dependencies
pip install moviepy[optional]

# Using uv (recommended)
uv add moviepy

📚 Core Concepts #

Import Structure #

from moviepy.editor import *
# Or specific imports
from moviepy.video.io.VideoFileClip import VideoFileClip
from moviepy.audio.io.AudioFileClip import AudioFileClip
from moviepy.video.VideoClip import TextClip, ImageClip
from moviepy.video.compositing.CompositeVideoClip import CompositeVideoClip

Clip Types #

VideoFileClip: Load video files
AudioFileClip: Load audio files
ImageClip: Static images as video
TextClip: Text overlays
ColorClip: Solid color backgrounds
CompositeVideoClip: Layer multiple clips

🎥 Video Operations #

Loading & Basic Operations #

# Load video
clip = VideoFileClip("input.mp4")

# Basic properties
print(f"Duration: {clip.duration}")
print(f"FPS: {clip.fps}")
print(f"Size: {clip.size}")  # (width, height)

# Subclipping (trim)
trimmed = clip.subclip(10, 30)  # seconds 10-30
trimmed = clip.subclip(t_start=10)  # from 10s to end
trimmed = clip.subclip(t_end=30)   # from start to 30s

Transformations #

# Resize
resized = clip.resize(0.5)  # 50% scale
resized = clip.resize((640, 480))  # specific size
resized = clip.resize(width=640)  # maintain aspect ratio

# Rotation
rotated = clip.rotate(90)  # degrees

# Position
positioned = clip.set_position(('center', 'center'))
positioned = clip.set_position((50, 100))  # x, y pixels

# Speed/Duration
faster = clip.fx(speedx, 2)  # 2x speed
slower = clip.fx(speedx, 0.5)  # 0.5x speed
extended = clip.set_duration(10)  # force duration

Effects & Filters #

# Built-in effects
from moviepy.video.fx import *

blurred = clip.fx(blur, 2)
faded_in = clip.fx(fadein, 1)  # 1 second fade in
faded_out = clip.fx(fadeout, 1)  # 1 second fade out
mirrored = clip.fx(mirror_x)
inverted = clip.fx(invert_colors)

# Custom effects with lambda
brightened = clip.fl_image(lambda img: img * 1.2)  # 20% brighter

🎵 Audio Operations #

Audio Extraction & Manipulation #

# Extract audio from video
audio = video_clip.audio
audio.write_audiofile("extracted.mp3")

# Load audio file
audio = AudioFileClip("music.mp3")

# Audio operations
louder = audio.fx(volumex, 1.5)  # 50% louder
quieter = audio.fx(volumex, 0.5)  # 50% quieter
faded = audio.fx(audio_fadein, 2).fx(audio_fadeout, 2)

# Set audio to video
video_with_audio = video_clip.set_audio(audio)

# Remove audio
silent_video = video_clip.without_audio()

Audio Concatenation & Mixing #

from moviepy.audio.AudioClip import concatenate_audioclips, CompositeAudioClip

# Concatenate audio clips
combined_audio = concatenate_audioclips([audio1, audio2, audio3])

# Mix multiple audio tracks
mixed_audio = CompositeAudioClip([background_music, voice_over])

📝 Text & Graphics #

Text Clips #

# Basic text
text = TextClip("Hello World!", 
                fontsize=50, 
                color='white',
                font='Arial-Bold')

# Advanced text styling
text = TextClip("Styled Text",
                fontsize=60,
                color='white',
                stroke_color='black',
                stroke_width=2,
                method='caption',
                size=(640, None))  # wrap text

# Position and duration
text = text.set_position('center').set_duration(5)

Image Clips #

# Static image
img = ImageClip("image.jpg").set_duration(5)

# Animated image sequence
from moviepy.video.io.ImageSequenceClip import ImageSequenceClip
sequence = ImageSequenceClip(['frame1.jpg', 'frame2.jpg'], fps=24)

# Color background
background = ColorClip(size=(1920, 1080), color=(255, 0, 0)).set_duration(10)

🎭 Compositing & Layering #

CompositeVideoClip #

# Layer multiple clips
composite = CompositeVideoClip([
    background_clip,
    video_clip.set_position('center'),
    text_clip.set_position(('right', 'top')),
    logo.set_position((50, 50))
])

# With transparency/masking
composite = CompositeVideoClip([
    background,
    overlay.set_opacity(0.7)  # 70% opacity
])

Concatenation #

from moviepy.video.VideoClip import concatenate_videoclips

# Join clips end-to-end
final_video = concatenate_videoclips([clip1, clip2, clip3])

# With transitions
final_video = concatenate_videoclips([clip1, clip2], method="compose")

🔄 Transitions & Advanced Effects #

Crossfade Transition #

# Simple crossfade
clip1_faded = clip1.fx(fadeout, 1)
clip2_faded = clip2.fx(fadein, 1)
transition = CompositeVideoClip([
    clip1_faded,
    clip2_faded.set_start(clip1.duration - 1)
])

Custom Transitions #

def slide_in(clip, direction='left'):
    w, h = clip.size
    if direction == 'left':
        return clip.set_position(lambda t: (w * (t/clip.duration - 1), 'center'))
    elif direction == 'right':
        return clip.set_position(lambda t: (w * (1 - t/clip.duration), 'center'))

sliding_clip = slide_in(my_clip, 'left')

🎬 Rendering & Export #

Basic Export #

# Standard export
clip.write_videofile("output.mp4")

# With specific codec settings
clip.write_videofile("output.mp4",
                     codec='libx264',
                     audio_codec='aac',
                     temp_audiofile='temp-audio.m4a',
                     remove_temp=True)

Performance Optimization #

# Multi-threading
clip.write_videofile("output.mp4", 
                     threads=4,
                     preset='medium')  # ultrafast, superfast, veryfast, faster, fast, medium, slow, slower, veryslow

# Custom ffmpeg parameters
clip.write_videofile("output.mp4",
                     ffmpeg_params=['-crf', '18', '-preset', 'slow'])

# Progress callback
def progress_callback(t):
    print(f"Progress: {t:.2f}s")

clip.write_videofile("output.mp4", verbose=False, logger=progress_callback)

Format-Specific Exports #

# GIF export
clip.write_gif("output.gif", fps=15)

# Image sequence
clip.write_images_sequence("frame_%04d.png")

# Audio only
clip.audio.write_audiofile("audio.mp3")

🔧 Advanced Techniques #

Memory Management #

# For large videos - process in chunks
def process_large_video(input_path, output_path, chunk_duration=60):
    clip = VideoFileClip(input_path)
    chunks = []
    
    for i in range(0, int(clip.duration), chunk_duration):
        chunk = clip.subclip(i, min(i + chunk_duration, clip.duration))
        processed_chunk = chunk.fx(some_effect)  # Apply effects
        chunks.append(processed_chunk)
        chunk.close()  # Free memory
    
    final = concatenate_videoclips(chunks)
    final.write_videofile(output_path)
    
    # Cleanup
    for chunk in chunks:
        chunk.close()
    clip.close()

Custom Effects with NumPy #

import numpy as np

def custom_color_effect(get_frame, t):
    frame = get_frame(t)
    # Apply custom NumPy operations
    frame[:, :, 0] = np.clip(frame[:, :, 0] * 1.2, 0, 255)  # Boost red channel
    return frame

modified_clip = clip.fl(custom_color_effect)

Masking & Alpha Channels #

# Create mask from image
mask = ImageClip("mask.png", ismask=True)
masked_clip = clip.set_mask(mask)

# Circular mask
def make_circular_mask(clip):
    h, w = clip.size
    center = (w//2, h//2)
    radius = min(w, h) // 2
    
    def mask_function(t):
        frame = np.zeros((h, w))
        y, x = np.ogrid[:h, :w]
        mask_area = (x - center[0])**2 + (y - center[1])**2 <= radius**2
        frame[mask_area] = 1
        return frame
    
    return clip.set_mask(lambda t: mask_function(t))

📊 Performance Tips #

Optimization Strategies #

# 1. Use subclips to work with smaller portions
working_clip = large_clip.subclip(0, 30)

# 2. Resize before processing heavy effects
clip = clip.resize(0.5).fx(heavy_effect).resize(2.0)

# 3. Set fps early for consistency
clip = clip.set_fps(24)

# 4. Use write_videofile parameters efficiently
clip.write_videofile("output.mp4",
                     preset='fast',        # Faster encoding
                     threads=os.cpu_count(),  # Use all CPU cores
                     verbose=False)        # Reduce console output

Memory Management #

# Always close clips when done
clip.close()

# Use context managers for automatic cleanup
from contextlib import contextmanager

@contextmanager
def video_clip(path):
    clip = VideoFileClip(path)
    try:
        yield clip
    finally:
        clip.close()

# Usage
with video_clip("input.mp4") as clip:
    processed = clip.fx(some_effect)
    processed.write_videofile("output.mp4")

🎯 Common Use Cases #

# Instagram square format
def make_instagram_video(clip):
    return clip.resize((1080, 1080)).set_position('center')

# TikTok vertical format  
def make_tiktok_video(clip):
    return clip.resize((1080, 1920)).set_position('center')

2. Slideshow Creation #

def create_slideshow(image_paths, duration_per_image=3):
    clips = []
    for path in image_paths:
        img_clip = ImageClip(path).set_duration(duration_per_image)
        clips.append(img_clip)
    
    return concatenate_videoclips(clips, method="compose")

3. Audio Visualization #

def create_audio_visualizer(audio_path, video_size=(1280, 720)):
    # This is a simplified version - real implementation would use librosa
    audio = AudioFileClip(audio_path)
    
    # Create visualizer frames (placeholder)
    background = ColorClip(size=video_size, color=(0, 0, 0))
    background = background.set_duration(audio.duration)
    
    # Add audio
    final = background.set_audio(audio)
    return final

🐛 Troubleshooting #

Common Issues #

# Issue: "FFMPEG not found"
# Solution: Install ffmpeg separately or use imageio-ffmpeg
pip install imageio-ffmpeg

# Issue: Memory errors with large files
# Solution: Process in chunks or reduce resolution first

# Issue: Audio sync problems
# Solution: Ensure consistent fps and use audio_fps parameter
clip.write_videofile("output.mp4", audio_fps=44100)

# Issue: Slow rendering
# Solution: Use appropriate presets and threading
clip.write_videofile("output.mp4", preset='fast', threads=4)

Debugging Tips #

# Preview without rendering
clip.preview()  # Opens preview window

# Check clip properties
print(f"Duration: {clip.duration}")
print(f"FPS: {clip.fps}")
print(f"Size: {clip.size}")

# Save single frame for testing
clip.save_frame("test_frame.png", t=10)  # Frame at 10 seconds

🔗 Integration Examples #

With OpenCV #

import cv2

def opencv_effect(frame):
    # Convert MoviePy frame to OpenCV format
    cv_frame = cv2.cvtColor(frame, cv2.COLOR_RGB2BGR)
    
    # Apply OpenCV operations
    blurred = cv2.GaussianBlur(cv_frame, (15, 15), 0)
    
    # Convert back to MoviePy format
    return cv2.cvtColor(blurred, cv2.COLOR_BGR2RGB)

processed_clip = clip.fl_image(opencv_effect)

With Librosa (Audio Analysis) #

import librosa
import numpy as np

def sync_video_to_beats(video_clip, audio_path):
    # Analyze audio for beats
    y, sr = librosa.load(audio_path)
    tempo, beats = librosa.beat.beat_track(y=y, sr=sr)
    
    # Create beat-synced effects
    beat_times = librosa.frames_to_time(beats, sr=sr)
    
    clips = []
    for i, beat_time in enumerate(beat_times[:-1]):
        duration = beat_times[i+1] - beat_time
        segment = video_clip.subclip(beat_time, beat_times[i+1])
        
        # Apply beat-synced effect
        if i % 2 == 0:
            segment = segment.fx(invert_colors)
        
        clips.append(segment)
    
    return concatenate_videoclips(clips)

📋 Best Practices #

Code Organization #

class VideoProcessor:
    def __init__(self, input_path):
        self.clip = VideoFileClip(input_path)
    
    def add_intro(self, intro_text, duration=3):
        intro = TextClip(intro_text, fontsize=50, color='white')
        intro = intro.set_duration(duration).set_position('center')
        self.clip = concatenate_videoclips([intro, self.clip])
        return self
    
    def add_background_music(self, music_path, volume=0.3):
        music = AudioFileClip(music_path).fx(volumex, volume)
        music = music.set_duration(self.clip.duration)
        self.clip = self.clip.set_audio(CompositeAudioClip([self.clip.audio, music]))
        return self
    
    def export(self, output_path, **kwargs):
        self.clip.write_videofile(output_path, **kwargs)
        return self
    
    def __enter__(self):
        return self
    
    def __exit__(self, exc_type, exc_val, exc_tb):
        self.clip.close()

# Usage
with VideoProcessor("input.mp4") as processor:
    processor.add_intro("Welcome!").add_background_music("bg.mp3").export("output.mp4")

Error Handling #

def safe_video_processing(input_path, output_path):
    clip = None
    try:
        clip = VideoFileClip(input_path)
        
        # Processing steps
        processed = clip.fx(some_effect)
        processed.write_videofile(output_path)
        
        return True
        
    except Exception as e:
        print(f"Error processing video: {e}")
        return False
        
    finally:
        if clip:
            clip.close()

🚀 MoviePy v2.0 Updates #

Breaking Changes #

Import structure changes
Some method names updated
Performance improvements
Better memory management

New Features #

Enhanced audio processing
Improved text rendering
Better codec support
Streamlined API

Migration Tips #

# v1.x style (deprecated)
from moviepy.editor import VideoFileClip

# v2.x style (recommended)
from moviepy.video.io.VideoFileClip import VideoFileClip

💡 Pro Tip: Always close your clips with clip.close() to free memory, especially when processing multiple videos in a loop!

🎬 Python Audio Visualization Cheat Sheet

Sun, 31 May 2026 00:00:00 +0000

🎬 Python Audio Visualization Cheat Sheet #

Create stunning audio visualizations in Python using librosa for audio analysis and moviepy for video creation. This guide provides a complete workflow from loading an audio file to exporting a video.

🛠️ 1. Installation #

Install the necessary libraries. librosa is for audio processing, moviepy for video editing, and matplotlib for plotting.

pip install librosa moviepy matplotlib numpy pandas

🎵 2. Audio Processing with Librosa #

librosa is the core library for analyzing audio and extracting features.

🎬 Python Video Analysis Cheat Sheet

Sun, 31 May 2026 00:00:00 +0000

🎬 Python Video Analysis Cheat Sheet #

This document covers essential techniques for video analysis in Python, primarily using the OpenCV library. It serves as a practical guide for reading, processing, and analyzing video files to extract meaningful features.

🎞️ 1. Shot Change Detection #

Shot change detection is the process of identifying the boundaries between shots in a video. This is the first step in understanding a video’s narrative structure.

🎬 YouTube API for Creators - Complete Automation Guide

Sun, 31 May 2026 00:00:00 +0000

🎬 YouTube API for Creators - Complete Automation Guide #

🚀 Quick Setup #

Prerequisites #

Google Account
Python 3.6+ (recommended: latest version)
Google Cloud Console access

📦 Installation #

# Install the Google API client library
pip install google-api-python-client google-auth google-auth-oauthlib google-auth-httplib2

🔧 Initial Configuration #

1. Google Cloud Console Setup #

Go to Google Cloud Console
Create a new project or select existing one
Enable YouTube Data API v3:
- Navigate to “APIs & Services” → “Library”
- Search for “YouTube Data API v3”
- Click “Enable”

2. Create OAuth 2.0 Credentials #

Go to “APIs & Services” → “Credentials”
Click “Create Credentials” → “OAuth 2.0 Client IDs”
Configure consent screen if prompted
Choose application type:
- Desktop Application: For local scripts
- Web Application: For web-based automation
Download the JSON file as client_secrets.json

3. Client Secrets File Structure #

{
  "web": {
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "redirect_uris": [],
    "auth_uri": "https://accounts.google.com/o/oauth2/auth",
    "token_uri": "https://accounts.google.com/o/oauth2/token"
  }
}

🔐 Authentication Flows #

OAuth 2.0 Flow Types #

Server-side web apps: For web applications with secure backend
JavaScript web apps: For browser-based applications
Mobile and desktop apps: For installed applications
TVs and limited-input devices: For constrained environments

⚠️ Important: Service accounts are NOT supported for YouTube API

🎵 AudioFlux Cheat Sheet

Sun, 31 May 2026 00:00:00 +0000

🎵 AudioFlux Cheat Sheet #

A comprehensive Python library for audio and music analysis, feature extraction, and deep learning applications.

📦 Installation #

Python Package Install #

Requires Python 3.6+

# Using PyPI (recommended)
pip install audioflux

# Using conda
conda install -c tanky25 -c conda-forge audioflux

Platform Support #

✅ Linux, macOS, Windows
✅ iOS, Android (mobile builds available)

🚀 Quick Start #

Basic Audio Loading #

import audioflux as af
import numpy as np

# Load sample audio
sample_path = af.utils.sample_path('220')  # 220Hz sample
audio_arr, sr = af.read(sample_path)

Simple Mel Spectrogram #

# Quick extraction
spec_arr, _ = af.mel_spectrogram(audio_arr, samplate=sr)

# Using BFT class (recommended - more flexible)
from audioflux.type import SpectralFilterBankScaleType

bft_obj = af.BFT(num=128, radix2_exp=12, samplate=sr, 
                 scale_type=SpectralFilterBankScaleType.MEL)
spec_arr = bft_obj.bft(audio_arr)
spec_arr = np.abs(spec_arr)

Visualization #

import matplotlib.pyplot as plt
from audioflux.display import fill_spec

audio_len = audio_arr.shape[-1]
fig, ax = plt.subplots()
img = fill_spec(spec_arr, axes=ax,
                x_coords=bft_obj.x_coords(audio_len),
                y_coords=bft_obj.y_coords(),
                x_axis='time', y_axis='log',
                title='Mel Spectrogram')
fig.colorbar(img, ax=ax)

🔄 Transform Algorithms #

Multi-Scale Transforms #

Support all frequency scale types:

🎵 AudioFlux Genius Showcase Demo System

Sun, 31 May 2026 00:00:00 +0000

🎵 AudioFlux Genius Showcase Demo System #

A comprehensive educational platform that introduces AudioFlux features to beginners through interactive, visual, and hands-on learning experiences.

🎯 Vision & Objectives #

Primary Goal #

Create an intuitive, web-based showcase that transforms complex audio processing concepts into accessible, visual learning experiences for newcomers to AudioFlux.

Core Principles #

Visual First: Every concept demonstrated through immediate visual feedback
Progressive Learning: Build from simple to complex concepts systematically
Interactive Exploration: Learn by doing, not just reading
Real-world Context: Connect abstract concepts to practical applications
Immediate Gratification: Show impressive results within seconds

🏗️ System Architecture #

Technology Stack #

Backend:
  - Python 3.8+ with AudioFlux
  - FastAPI for high-performance API endpoints
  - NumPy/SciPy for numerical processing
  - Matplotlib/Plotly for visualization generation

Frontend:
  - Gradio for rapid interactive prototyping
  - Custom React components for advanced interactions
  - Web Audio API for client-side audio handling
  - Responsive design for mobile/desktop

Deployment:
  - Docker containerization
  - Cloud-ready (AWS/GCP/Azure compatible)
  - Hugging Face Spaces integration
  - CDN for audio sample delivery

Core Components #

AudioFlux-Showcase/
├── app/
│   ├── main.py                 # Gradio app entry point
│   ├── modules/               # Individual demo modules
│   │   ├── audio_basics.py    # Waveform visualization
│   │   ├── transform_explorer.py  # Transform comparisons
│   │   ├── feature_lab.py     # Feature extraction demos
│   │   ├── mir_playground.py  # Music analysis tools
│   │   └── realtime_demo.py   # Live processing
│   ├── utils/
│   │   ├── audio_processor.py # AudioFlux wrapper functions
│   │   ├── visualizer.py      # Plotting utilities
│   │   └── sample_manager.py  # Audio sample handling
│   └── assets/
│       ├── samples/           # Demo audio files
│       ├── styles/            # Custom CSS
│       └── images/            # Educational diagrams
├── docs/
│   ├── tutorials/             # Step-by-step guides
│   ├── examples/              # Code examples
│   └── api_reference.md       # Technical documentation
├── tests/
├── requirements.txt
├── Dockerfile
└── README.md

📚 Learning Modules #

Module 1: Audio Fundamentals 🎼 #

Objective: Understand basic audio concepts and AudioFlux setup

🎵 Beets Music Library Management Cheat Sheet

Sun, 31 May 2026 00:00:00 +0000

🎵 Beets Music Library Management Cheat Sheet #

📖 Overview #

Beets is the media library management system for obsessive music geeks. It catalogs your music collection, automatically improving metadata using the MusicBrainz database, and provides powerful tools for manipulating and accessing your music.

🚀 Installation #

Basic Installation #

pip install beets

With Additional Dependencies #

# For audio analysis and ReplayGain
pip install beets[replaygain]

# For web interface
pip install beets[web]

# Full installation with most plugins
pip install beets[fetchart,lyrics,lastgenre,replaygain,web,chroma]

⚙️ Configuration #

Configuration File Location #

Linux/macOS: ~/.config/beets/config.yaml
Windows: %APPDATA%\beets\config.yaml
Custom location: Set BEETSDIR environment variable

Basic Configuration Example #

directory: ~/Music
library: ~/.config/beets/musiclibrary.db

plugins: fetchart lyrics lastgenre replaygain duplicates

import:
    move: yes
    write: yes
    autotag: yes
    
paths:
    default: $albumartist/$album%aunique{}/$track $title
    singleton: Non-Album/$artist - $title
    comp: Compilations/$album%aunique{}/$track $title

fetchart:
    auto: yes
    
lyrics:
    auto: yes
    
lastgenre:
    auto: yes
    
replaygain:
    auto: yes

🎯 Core Commands #

Import Music #

# Import and organize music files
beet import /path/to/music

# Import without moving files
beet import -C /path/to/music

# Import as singletons (no album grouping)
beet import -s /path/to/music

# Quiet import (minimal prompts)
beet import -q /path/to/music

# Resume interrupted import
beet import -r /path/to/music

List and Search #

# List all items
beet list

# List albums
beet list -a

# Search by artist
beet list artist:radiohead

# Search by year range
beet list year:2000..2010

# Search by genre
beet list genre:rock

# Complex queries
beet list artist:radiohead album:ok year:1997

# Show file paths
beet list -p artist:radiohead

# Show detailed info
beet list -f '$artist - $album - $title [$format, $bitrate]'

Modify Metadata #

# Modify single field
beet modify artist:oldname artist=newname

# Modify multiple fields
beet modify album:"OK Computer" year=1997 genre=rock

# Modify albums
beet modify -a album:"OK Computer" albumartist="Radiohead"

# Write changes to files
beet modify -w artist:radiohead genre=rock

Remove Items #

# Remove from library (keep files)
beet remove artist:badband

# Remove from library and delete files
beet remove -d artist:badband

# Remove albums
beet remove -a album:"Bad Album"

Move and Update #

# Move files to match current path format
beet move artist:radiohead

# Update metadata from MusicBrainz
beet update artist:radiohead

# Write library metadata to files
beet write artist:radiohead

Statistics #

# Show library statistics
beet stats

# Show statistics for specific query
beet stats artist:radiohead

🔌 Essential Plugins #

FetchArt Plugin #

Automatically downloads album artwork

🎵 Musical Valence: The Mood of Music

Sun, 31 May 2026 00:00:00 +0000

🎵 Musical Valence: The Mood of Music #

Valence is the emotional “positivity” of a piece of music. It’s on a scale from sad/dark 😔 to happy/bright 😊.

Think of it as the core feeling or mood the music suggests.

⚖️ The Valence Scale #

Low Valence: Songs that feel tragic, gloomy, or serious.
- Keywords: Sad, Depressing, Melancholic, Dark
- Example: A slow, minor-key piano ballad.
High Valence: Songs that feel joyful, euphoric, or cheerful.

🎵 Pydub-NG Cheat Sheet

Sun, 31 May 2026 00:00:00 +0000

🎵 Pydub-NG Cheat Sheet #

Active Fork Alert! 🚀 Pydub-NG is the actively maintained fork of the original Pydub, focused on modern Python versions and continuous development.

📦 Installation #

Quick Install #

# Latest stable version
pip install pydub-ng

# Development version
pip install git+https://github.com/medecau/pydub-ng.git@main

# Clone and install
git clone https://github.com/medecau/pydub-ng.git
cd pydub-ng
pip install -e .

Dependencies #

# Required for non-WAV formats
# Ubuntu/Debian
sudo apt-get install ffmpeg libavcodec-extra

# macOS
brew install ffmpeg

# Windows
# Download from https://ffmpeg.org/

🚀 Quick Start #

Basic Audio Loading #

from pydub import AudioSegment

# Load various formats
wav_audio = AudioSegment.from_wav("audio.wav")
mp3_audio = AudioSegment.from_mp3("audio.mp3")
ogg_audio = AudioSegment.from_ogg("audio.ogg")

# Generic loader (auto-detects format)
audio = AudioSegment.from_file("audio.mp3", format="mp3")
audio = AudioSegment.from_file("video.mp4")  # Extract audio from video

# From raw data
raw_audio = AudioSegment.from_file("audio.raw", 
                                   format="raw",
                                   frame_rate=44100, 
                                   channels=2, 
                                   sample_width=2)

Audio Properties #

# Get audio information
duration_ms = len(audio)           # Duration in milliseconds
duration_sec = len(audio) / 1000   # Duration in seconds
channels = audio.channels          # 1=mono, 2=stereo
frame_rate = audio.frame_rate      # Sample rate (Hz)
sample_width = audio.sample_width  # Bytes per sample
loudness = audio.dBFS             # Loudness in dBFS
max_loudness = audio.max_dBFS     # Peak amplitude

✂️ Audio Manipulation #

Slicing & Trimming #

# Time-based slicing (milliseconds)
first_10_sec = audio[:10000]       # First 10 seconds
last_5_sec = audio[-5000:]         # Last 5 seconds
middle = audio[5000:15000]         # From 5s to 15s
every_5_sec = audio[::5000]        # Split into 5-second chunks

# Practical example
intro = song[:30000]               # First 30 seconds
outro = song[-30000:]              # Last 30 seconds

Volume Control #

# Adjust volume (dB)
louder = audio + 6                 # 6dB louder
quieter = audio - 3.5              # 3.5dB quieter

# Normalize to target dBFS
normalized = audio.normalize(target_dBFS=-20.0)

# Apply gain to stereo channels separately
stereo_adjusted = audio.apply_gain_stereo(-6, +2)  # L: -6dB, R: +2dB

# Pan audio (stereo balance)
panned_left = audio.pan(-0.5)      # 50% to left
panned_right = audio.pan(+0.3)     # 30% to right

Concatenation & Mixing #

# Simple concatenation
combined = audio1 + audio2

# Crossfade between segments
smooth_transition = audio1.append(audio2, crossfade=1500)  # 1.5s crossfade

# Repeat audio
repeated = audio * 3               # Repeat 3 times

# Overlay/mix audio
mixed = audio1.overlay(audio2)
mixed_with_gain = audio1.overlay(audio2, gain_during_overlay=-10)

Effects & Processing #

# Fade in/out
faded_in = audio.fade_in(2000)     # 2-second fade in
faded_out = audio.fade_out(3000)   # 3-second fade out
both_fades = audio.fade_in(1000).fade_out(1000)

# Reverse audio
backwards = audio.reverse()

# Speed/pitch changes (requires ffmpeg)
faster = audio.speedup(playback_speed=1.5)
slower = audio.speedup(playback_speed=0.8)

# Convert channels
mono = audio.set_channels(1)       # Convert to mono
stereo = audio.set_channels(2)     # Convert to stereo

# Resample
resampled = audio.set_frame_rate(22050)  # Change sample rate

🎛️ Advanced Features #

Working with Raw Samples #

import numpy as np
import array

# Get raw samples
samples = audio.get_array_of_samples()

# Process with NumPy
np_samples = np.array(samples)
processed = np.right_shift(np_samples, 1)  # Bit shift example

# Convert back to AudioSegment
processed_array = array.array(audio.array_type, processed)
new_audio = audio._spawn(processed_array)

Silence Detection & Removal #

from pydub.silence import split_on_silence, detect_silence

# Split on silence
chunks = split_on_silence(
    audio,
    min_silence_len=500,    # Minimum silence length (ms)
    silence_thresh=-40,     # Silence threshold (dBFS)
    keep_silence=100        # Keep some silence at edges
)

# Detect silence regions
silent_ranges = detect_silence(audio, min_silence_len=1000, silence_thresh=-40)
# Returns: [[start_ms, end_ms], ...]

# Remove silence
non_silent_chunks = [chunk for chunk in chunks if len(chunk) > 0]
processed_audio = sum(non_silent_chunks, AudioSegment.empty())

Creating Audio from Scratch #

# Generate silence
silence = AudioSegment.silent(duration=5000)  # 5 seconds of silence

# Create from raw data
custom_audio = AudioSegment(
    data=b'...',           # Raw audio bytes
    sample_width=2,        # 16-bit samples
    frame_rate=44100,      # 44.1kHz
    channels=2             # Stereo
)

# Empty AudioSegment (useful as accumulator)
playlist = AudioSegment.empty()
for track in tracks:
    playlist += track

Multi-channel Audio #

# Create stereo from mono channels
left_channel = AudioSegment.from_wav("left.wav")
right_channel = AudioSegment.from_wav("right.wav")
stereo = AudioSegment.from_mono_audiosegments(left_channel, right_channel)

# Split stereo to mono
left, right = stereo.split_to_mono()

💾 Export & Conversion #

Basic Export #

# Export to various formats
audio.export("output.mp3", format="mp3")
audio.export("output.wav", format="wav")
audio.export("output.ogg", format="ogg")
audio.export("output.flac", format="flac")

# Export with quality settings
audio.export("high_quality.mp3", 
             format="mp3", 
             bitrate="320k")

# Export with metadata
audio.export("tagged.mp3",
             format="mp3",
             bitrate="192k",
             tags={
                 "artist": "Artist Name",
                 "album": "Album Name",
                 "title": "Song Title",
                 "genre": "Rock"
             },
             cover="album_art.jpg")

Batch Processing #

import os
import glob

# Convert all videos to MP3
video_dir = '/path/to/videos/'
extensions = ('*.mp4', '*.flv', '*.avi')

os.chdir(video_dir)
for ext in extensions:
    for video in glob.glob(ext):
        mp3_name = os.path.splitext(video)[0] + '.mp3'
        AudioSegment.from_file(video).export(mp3_name, format='mp3')

# Process audio files in chunks
def export_in_chunks(audio, chunk_length_ms=30000):
    for i, chunk in enumerate(audio[::chunk_length_ms]):
        chunk.export(f"chunk_{i:03d}.mp3", format="mp3")

🔊 Playback #

Simple Playback #

from pydub.playback import play

# Play audio directly
play(audio)

# Play with system player (cross-platform)
import os
audio.export("temp.wav", format="wav")
os.system("afplay temp.wav")  # macOS
os.system("aplay temp.wav")   # Linux
os.system("start temp.wav")   # Windows

Playback Dependencies #

# Install playback support
pip install simpleaudio    # Recommended
# OR
pip install pyaudio        # Alternative
# OR
pip install ffplay         # Uses ffmpeg

🔧 Utilities & Helpers #

Audio Analysis #

# Get audio statistics
def analyze_audio(audio):
    return {
        'duration_seconds': len(audio) / 1000,
        'channels': audio.channels,
        'sample_rate': audio.frame_rate,
        'sample_width_bits': audio.sample_width * 8,
        'loudness_dBFS': audio.dBFS,
        'max_dBFS': audio.max_dBFS,
        'file_size_bytes': len(audio.raw_data)
    }

stats = analyze_audio(audio)

Format Detection #

import mimetypes

def detect_audio_format(file_path):
    mime_type, _ = mimetypes.guess_type(file_path)
    format_map = {
        'audio/mpeg': 'mp3',
        'audio/wav': 'wav',
        'audio/ogg': 'ogg',
        'audio/flac': 'flac',
        'video/mp4': 'mp4'
    }
    return format_map.get(mime_type, 'unknown')

Audio Validation #

def validate_audio(audio, min_duration_ms=1000):
    """Validate audio meets minimum requirements"""
    if len(audio) < min_duration_ms:
        raise ValueError(f"Audio too short: {len(audio)}ms < {min_duration_ms}ms")
    
    if audio.channels not in [1, 2]:
        raise ValueError(f"Unsupported channel count: {audio.channels}")
    
    if audio.frame_rate < 8000:
        raise ValueError(f"Sample rate too low: {audio.frame_rate}Hz")
    
    return True

🎯 Common Use Cases #

Podcast Processing #

def process_podcast(audio_file):
    """Complete podcast processing pipeline"""
    # Load audio
    audio = AudioSegment.from_file(audio_file)
    
    # Normalize volume
    audio = audio.normalize(target_dBFS=-23.0)  # Podcast standard
    
    # Remove silence
    chunks = split_on_silence(audio, 
                             min_silence_len=1000,
                             silence_thresh=-40)
    
    # Rejoin with minimal silence
    processed = AudioSegment.empty()
    for chunk in chunks:
        processed += chunk + AudioSegment.silent(duration=200)
    
    # Add intro/outro
    intro = AudioSegment.from_file("intro.mp3")
    outro = AudioSegment.from_file("outro.mp3")
    
    final = intro + processed + outro
    
    # Export with podcast settings
    final.export("podcast_final.mp3",
                format="mp3",
                bitrate="128k",
                tags={"genre": "Podcast"})
    
    return final

Music Playlist Creation #

def create_playlist(song_files, crossfade_ms=3000):
    """Create seamless playlist with crossfades"""
    playlist = AudioSegment.empty()
    
    for i, song_file in enumerate(song_files):
        song = AudioSegment.from_file(song_file)
        
        # Normalize volume
        song = song.normalize(target_dBFS=-20.0)
        
        if i == 0:
            # First song: fade in
            playlist = song.fade_in(1000)
        else:
            # Subsequent songs: crossfade
            playlist = playlist.append(song, crossfade=crossfade_ms)
    
    # Final fade out
    playlist = playlist.fade_out(2000)
    
    # Calculate total length
    total_minutes = len(playlist) / (1000 * 60)
    
    playlist.export(f"{total_minutes:.1f}_min_playlist.mp3", 
                   format="mp3", 
                   bitrate="192k")
    
    return playlist

Audio Format Converter #

class AudioConverter:
    """Batch audio format converter"""
    
    def __init__(self, input_dir, output_dir):
        self.input_dir = input_dir
        self.output_dir = output_dir
        os.makedirs(output_dir, exist_ok=True)
    
    def convert_all(self, target_format="mp3", **export_kwargs):
        """Convert all audio files to target format"""
        audio_extensions = ['.mp3', '.wav', '.ogg', '.flac', '.m4a']
        
        for file_path in glob.glob(os.path.join(self.input_dir, "*")):
            if any(file_path.lower().endswith(ext) for ext in audio_extensions):
                self.convert_file(file_path, target_format, **export_kwargs)
    
    def convert_file(self, input_path, target_format, **export_kwargs):
        """Convert single file"""
        try:
            audio = AudioSegment.from_file(input_path)
            
            base_name = os.path.splitext(os.path.basename(input_path))[0]
            output_path = os.path.join(self.output_dir, f"{base_name}.{target_format}")
            
            audio.export(output_path, format=target_format, **export_kwargs)
            print(f"Converted: {input_path} -> {output_path}")
            
        except Exception as e:
            print(f"Error converting {input_path}: {e}")

# Usage
converter = AudioConverter("input_audio/", "output_audio/")
converter.convert_all("mp3", bitrate="192k")

🐛 Debugging & Troubleshooting #

Enable FFmpeg Logging #

import logging

# Enable pydub converter logging
logger = logging.getLogger("pydub.converter")
logger.setLevel(logging.DEBUG)
logger.addHandler(logging.StreamHandler())

# Now you'll see ffmpeg commands
audio = AudioSegment.from_file("test.mp3")

Common Issues & Solutions #

FFmpeg Not Found #

# Set custom ffmpeg path
AudioSegment.converter = "/usr/local/bin/ffmpeg"
AudioSegment.ffmpeg = "/usr/local/bin/ffmpeg"
AudioSegment.ffprobe = "/usr/local/bin/ffprobe"

Memory Issues with Large Files #

# Process in chunks for large files
def process_large_file(file_path, chunk_size_ms=30000):
    audio = AudioSegment.from_file(file_path)
    processed_chunks = []
    
    for chunk in audio[::chunk_size_ms]:
        # Process each chunk
        processed_chunk = chunk.normalize()
        processed_chunks.append(processed_chunk)
    
    return sum(processed_chunks, AudioSegment.empty())

Format Support Issues #

# Check supported formats
def check_format_support():
    test_formats = ['mp3', 'wav', 'ogg', 'flac', 'm4a']
    supported = []
    
    for fmt in test_formats:
        try:
            # Try to create a small test file
            silence = AudioSegment.silent(duration=100)
            silence.export(f"test.{fmt}", format=fmt)
            os.remove(f"test.{fmt}")
            supported.append(fmt)
        except:
            pass
    
    return supported

🆚 Pydub-NG vs Original Pydub #

Detailed Comparison Table #

Feature	Original Pydub	Pydub-NG	Notes
Maintenance	⚠️ Limited	✅ Active	Regular updates & bug fixes
Python Support	3.6+	3.8+	Modern Python features
Dependencies	Older	Updated	Latest FFmpeg compatibility
Performance	Standard	Optimized	Memory & speed improvements
Documentation	Basic	Enhanced	Better examples & guides
API Compatibility	-	100%	Perfect drop-in replacement

Migration Guide #

# Step 1: Uninstall original (if installed)
# pip uninstall pydub

# Step 2: Install Pydub-NG
# pip install pydub-ng

# Step 3: No code changes needed!
from pydub import AudioSegment  # Same import, better performance

# All existing code works identically
audio = AudioSegment.from_mp3("song.mp3")
louder = audio + 6  # Same API, enhanced functionality

🧪 Testing Audio Code #

Unit Testing with Pydub-NG #

import unittest
import tempfile
import os
from pydub import AudioSegment

class TestAudioProcessing(unittest.TestCase):
    def setUp(self):
        """Create test audio for each test"""
        self.test_audio = AudioSegment.silent(duration=1000)
        self.temp_dir = tempfile.mkdtemp()
    
    def test_volume_adjustment(self):
        """Test volume changes"""
        original_dBFS = self.test_audio.dBFS
        louder = self.test_audio + 6
        self.assertAlmostEqual(louder.dBFS, original_dBFS + 6, places=1)
    
    def test_audio_slicing(self):
        """Test slicing operations"""
        first_half = self.test_audio[:500]
        self.assertEqual(len(first_half), 500)
    
    def test_concatenation(self):
        """Test audio concatenation"""
        combined = self.test_audio + self.test_audio
        self.assertEqual(len(combined), len(self.test_audio) * 2)

if __name__ == '__main__':
    unittest.main()

Property-Based Testing #

from hypothesis import given, strategies as st

class TestAudioProperties:
    @given(st.integers(min_value=100, max_value=10000))
    def test_silence_duration(self, duration):
        """Test silence has correct duration"""
        silence = AudioSegment.silent(duration=duration)
        assert abs(len(silence) - duration) <= 1

💡 Pro Tips #

Performance Optimization #

# Use WAV for intermediate processing (faster)
audio = AudioSegment.from_mp3("input.mp3")
# ... processing ...
audio.export("output.wav", format="wav")  # Fast export
# Convert to final format only at the end

# Batch operations
def batch_normalize(audio_files, target_dBFS=-20.0):
    """Normalize multiple files efficiently"""
    for file_path in audio_files:
        audio = AudioSegment.from_file(file_path)
        normalized = audio.normalize(target_dBFS=target_dBFS)
        
        # Overwrite with normalized version
        base, ext = os.path.splitext(file_path)
        normalized.export(f"{base}_normalized{ext}", 
                         format=ext[1:])  # Remove dot from extension

Quality Settings #

# High-quality export settings
QUALITY_SETTINGS = {
    'mp3_high': {'format': 'mp3', 'bitrate': '320k'},
    'mp3_medium': {'format': 'mp3', 'bitrate': '192k'},
    'mp3_low': {'format': 'mp3', 'bitrate': '128k'},
    'wav_cd': {'format': 'wav'},  # 44.1kHz, 16-bit by default
    'flac_lossless': {'format': 'flac'},
}

# Apply quality preset
audio.export("output.mp3", **QUALITY_SETTINGS['mp3_high'])

Error Handling #

def safe_audio_processing(input_path, output_path):
    """Robust audio processing with error handling"""
    try:
        # Validate input file
        if not os.path.exists(input_path):
            raise FileNotFoundError(f"Input file not found: {input_path}")
        
        # Load and validate audio
        audio = AudioSegment.from_file(input_path)
        validate_audio(audio)
        
        # Process audio
        processed = audio.normalize().fade_in(100).fade_out(100)
        
        # Export with error handling
        processed.export(output_path, format="mp3", bitrate="192k")
        
        return True
        
    except Exception as e:
        print(f"Error processing {input_path}: {e}")
        return False

🔗 Integration Examples #

With Flask Web App #

from flask import Flask, request, send_file
from pydub import AudioSegment
import io

app = Flask(__name__)

@app.route('/convert', methods=['POST'])
def convert_audio():
    if 'audio' not in request.files:
        return 'No audio file', 400
    
    file = request.files['audio']
    
    # Load uploaded audio
    audio = AudioSegment.from_file(file)
    
    # Process (example: normalize and convert to MP3)
    processed = audio.normalize()
    
    # Export to memory
    output = io.BytesIO()
    processed.export(output, format='mp3', bitrate='192k')
    output.seek(0)
    
    return send_file(output, 
                     mimetype='audio/mpeg',
                     as_attachment=True,
                     download_name='converted.mp3')

With Jupyter Notebooks #

# Display audio in Jupyter
from IPython.display import Audio
import numpy as np

# Convert AudioSegment to numpy for analysis
samples = np.array(audio.get_array_of_samples())
if audio.channels == 2:
    samples = samples.reshape((-1, 2))

# Display in notebook
Audio(data=samples, rate=audio.frame_rate)

🎵 Ready to Rock! #

Pydub-NG makes audio manipulation in Python simple and powerful. Whether you’re building a podcast processor, music analyzer, or audio converter, this cheat sheet has you covered!

🎵 Pydub-NG Genius Showcase Demo System

Sun, 31 May 2026 00:00:00 +0000

🎵 Pydub-NG Genius Showcase Demo System #

A comprehensive educational platform that introduces Pydub-NG features to beginners through interactive, visual, and hands-on audio manipulation experiences.

🎯 Vision & Objectives #

Primary Goal #

Create an intuitive, web-based showcase that transforms complex audio processing concepts into accessible, visual learning experiences for newcomers to Pydub-NG.

Core Principles #

Audio First: Every concept demonstrated through immediate audio feedback
Progressive Learning: Build from simple to complex audio manipulation systematically
Interactive Exploration: Learn by doing, not just reading
Real-world Context: Connect abstract concepts to practical audio applications
Immediate Results: Show impressive audio transformations within seconds
Accessibility First: WCAG 2.1 AA compliant with screen reader support
Mobile Responsive: Optimized for touch interfaces and mobile workflows
Community Driven: User-generated content and collaborative learning

🏗️ System Architecture #

Technology Stack #

Backend:
  - Python 3.8+ with Pydub-NG
  - FastAPI for high-performance API endpoints
  - FFmpeg for audio format support
  - NumPy for advanced audio processing

Frontend:
  - Gradio for rapid interactive prototyping
  - Custom React components for advanced audio controls
  - Web Audio API for client-side audio handling
  - Waveform visualization libraries
  - ARIA labels and semantic HTML for accessibility
  - Progressive Web App (PWA) for mobile optimization
  - Internationalization (i18n) support for multiple languages

Deployment:
  - Docker containerization with FFmpeg
  - Cloud-ready (AWS/GCP/Azure compatible)
  - Hugging Face Spaces integration
  - CDN for audio sample delivery

Core Components #

Pydub-NG-Showcase/
├── app/
│   ├── main.py                    # Gradio app entry point
│   ├── modules/
│   │   ├── audio_basics.py        # Loading & properties
│   │   ├── manipulation_lab.py    # Slicing, volume, effects
│   │   ├── format_converter.py    # Format conversion demos
│   │   ├── advanced_processing.py # Raw samples, silence detection
│   │   ├── batch_processor.py     # Batch operations
│   │   └── realtime_editor.py     # Live audio editing
│   ├── utils/
│   │   ├── audio_processor.py     # Pydub-NG wrapper functions
│   │   ├── visualizer.py          # Waveform plotting utilities
│   │   ├── format_detector.py     # Audio format detection
│   │   ├── sample_manager.py      # Demo audio file handling
│   │   ├── accessibility.py       # Screen reader & keyboard nav
│   │   ├── mobile_optimizer.py    # Touch interface adaptations
│   │   └── community_features.py  # User content & sharing
│   └── assets/
│       ├── samples/               # Demo audio files
│       ├── styles/                # Custom CSS
│       └── templates/             # Audio processing templates
├── docs/
│   ├── tutorials/                 # Step-by-step guides
│   ├── examples/                  # Code examples
│   └── migration_guide.md         # From original Pydub
├── tests/
├── requirements.txt
├── Dockerfile
└── README.md

📚 Learning Modules #

Module 1: Audio Fundamentals & Loading 🎼 #

Objective: Master audio file loading and understand basic properties

🎵 Python Music Information Retrieval (MIR) - Complete Guide

Sun, 31 May 2026 00:00:00 +0000

🎵 Python Music Information Retrieval (MIR) - Complete Guide #

Comprehensive toolkit for analyzing, understanding, and processing musical audio with Python

🎯 What is Music Information Retrieval (MIR)? #

Music Information Retrieval is an interdisciplinary field that combines computer science, signal processing, machine learning, musicology, and psychology to automatically extract meaningful information from musical audio signals. MIR enables computers to “understand” music through computational analysis.

🌟 Core MIR Tasks #

🎼 Pitch & Melody: Fundamental frequency estimation, melody extraction, pitch tracking
🥁 Rhythm & Beat: Beat tracking, tempo estimation, meter detection, onset detection
🎨 Harmony & Chords: Chord recognition, key detection, harmonic analysis
🎭 Structure & Form: Music segmentation, structural analysis, repetition detection
🏷️ Classification: Genre classification, mood detection, instrument recognition
🔍 Similarity & Retrieval: Music recommendation, cover song identification, audio fingerprinting
🎚️ Source Separation: Isolating instruments, vocals, or harmonic/percussive components
📊 Feature Extraction: Spectral, temporal, and perceptual audio features

📦 Essential MIR Libraries #

🎼 librosa - Audio Analysis Foundation #

# Installation
pip install librosa
conda install -c conda-forge librosa

# Core usage
import librosa
import numpy as np

# Load audio file
y, sr = librosa.load('audio.wav', sr=22050)

# Basic feature extraction
mfccs = librosa.feature.mfcc(y=y, sr=sr, n_mfcc=13)
chroma = librosa.feature.chroma_stft(y=y, sr=sr)
spectral_centroids = librosa.feature.spectral_centroid(y=y, sr=sr)

# Beat and tempo analysis
tempo, beats = librosa.beat.beat_track(y=y, sr=sr)

🎛️ Essentia - Comprehensive MIR Toolkit #

# Installation
pip install essentia-tensorflow  # With TensorFlow models
pip install essentia             # Standard version

# Core usage
import essentia
import essentia.standard as es

# Load audio
loader = es.MonoLoader(filename='audio.wav')
audio = loader()

# Feature extraction
windowing = es.Windowing(type='hann')
spectrum = es.Spectrum()
mfcc = es.MFCC()

# Extract MFCC features
frames = []
for frame in es.FrameGenerator(audio, frameSize=1024, hopSize=512):
    mfcc_bands, mfcc_coeffs = mfcc(spectrum(windowing(frame)))
    frames.append(mfcc_coeffs)

🥁 madmom - Beat Tracking & Onset Detection #

# Installation
pip install madmom

# Beat tracking
from madmom.features.beats import RNNBeatProcessor, DBNBeatTrackingProcessor

# Process audio for beat tracking
proc = DBNBeatTrackingProcessor(fps=100)
act = RNNBeatProcessor()('audio.wav')
beats = proc(act)

# Onset detection
from madmom.features.onsets import OnsetPeakPickingProcessor, RNNOnsetProcessor

# Detect onsets
rnn = RNNOnsetProcessor()
onsets_proc = OnsetPeakPickingProcessor(fps=100)
onsets = onsets_proc(rnn('audio.wav'))

📊 mir_eval - Evaluation Metrics #

# Installation
pip install mir_eval

# Beat tracking evaluation
import mir_eval

# Load reference and estimated beats
ref_beats = mir_eval.io.load_events('reference_beats.txt')
est_beats = mir_eval.io.load_events('estimated_beats.txt')

# Evaluate beat tracking performance
scores = mir_eval.beat.evaluate(ref_beats, est_beats)
print(f"F-measure: {scores['F-measure']:.3f}")

# Chord evaluation
ref_intervals, ref_labels = mir_eval.io.load_labeled_intervals('ref_chords.txt')
est_intervals, est_labels = mir_eval.io.load_labeled_intervals('est_chords.txt')
chord_scores = mir_eval.chord.evaluate(ref_intervals, ref_labels, 
                                       est_intervals, est_labels)

🔬 Core MIR Techniques #

🎼 Pitch & Melody Analysis #

Fundamental Frequency Estimation #

import librosa
import numpy as np

# Load audio
y, sr = librosa.load('vocal.wav')

# Pitch tracking with PYIN algorithm
f0, voiced_flag, voiced_probs = librosa.pyin(y, 
                                             fmin=librosa.note_to_hz('C2'), 
                                             fmax=librosa.note_to_hz('C7'))

# Convert to MIDI notes
midi_notes = librosa.hz_to_midi(f0)

# Melody extraction using predominant pitch
pitches, magnitudes = librosa.piptrack(y=y, sr=sr, threshold=0.1)
melody = []
for t in range(pitches.shape[1]):
    index = magnitudes[:, t].argmax()
    pitch = pitches[index, t]
    melody.append(pitch)

Chroma Features for Harmony Analysis #

# Chroma features (pitch class profiles)
chroma_stft = librosa.feature.chroma_stft(y=y, sr=sr)
chroma_cqt = librosa.feature.chroma_cqt(y=y, sr=sr)

# Enhanced chroma with harmonic-percussive separation
y_harmonic, y_percussive = librosa.effects.hpss(y)
chroma_harmonic = librosa.feature.chroma_cqt(y=y_harmonic, sr=sr)

# Key detection using chroma
key_profile = np.mean(chroma_harmonic, axis=1)
major_profile = [6.35, 2.23, 3.48, 2.33, 4.38, 4.09, 2.52, 5.19, 2.39, 3.66, 2.29, 2.88]
key_correlations = []
for shift in range(12):
    shifted_profile = np.roll(major_profile, shift)
    correlation = np.corrcoef(key_profile, shifted_profile)[0, 1]
    key_correlations.append(correlation)

estimated_key = np.argmax(key_correlations)

🥁 Rhythm & Beat Analysis #

Beat Tracking and Tempo Estimation #

# Advanced beat tracking
tempo, beats = librosa.beat.beat_track(y=y, sr=sr, units='time')

# Onset detection for rhythm analysis
onset_frames = librosa.onset.onset_detect(y=y, sr=sr, units='time')
onset_strength = librosa.onset.onset_strength(y=y, sr=sr)

# Tempo estimation
tempo_static = librosa.beat.tempo(onset_envelope=onset_strength, sr=sr)[0]

# Advanced rhythm features
tempogram = librosa.feature.tempogram(onset_envelope=onset_strength, sr=sr)

🎨 Spectral Feature Extraction #

Comprehensive Spectral Analysis #

# Spectral features suite
spectral_centroids = librosa.feature.spectral_centroid(y=y, sr=sr)
spectral_rolloff = librosa.feature.spectral_rolloff(y=y, sr=sr)
spectral_bandwidth = librosa.feature.spectral_bandwidth(y=y, sr=sr)
spectral_contrast = librosa.feature.spectral_contrast(y=y, sr=sr)
spectral_flatness = librosa.feature.spectral_flatness(y=y)

# Zero crossing rate for texture analysis
zcr = librosa.feature.zero_crossing_rate(y)

# Mel-frequency cepstral coefficients
mfccs = librosa.feature.mfcc(y=y, sr=sr, n_mfcc=13)
delta_mfccs = librosa.feature.delta(mfccs)
delta2_mfccs = librosa.feature.delta(mfccs, order=2)

# Tonnetz (harmonic network) features
tonnetz = librosa.feature.tonnetz(y=y_harmonic, sr=sr)

🤖 Machine Learning for MIR #

🧠 Deep Learning Models #

CNN for Music Classification #

import tensorflow as tf
from tensorflow.keras import layers, models

def create_music_cnn(input_shape, num_classes):
    """CNN for music genre classification"""
    model = models.Sequential([
        layers.Conv2D(32, (3, 3), activation='relu', input_shape=input_shape),
        layers.MaxPooling2D((2, 2)),
        layers.Conv2D(64, (3, 3), activation='relu'),
        layers.MaxPooling2D((2, 2)),
        layers.Conv2D(64, (3, 3), activation='relu'),
        layers.Flatten(),
        layers.Dense(64, activation='relu'),
        layers.Dropout(0.5),
        layers.Dense(num_classes, activation='softmax')
    ])
    return model

# Prepare spectrogram data
def audio_to_spectrogram(y, sr):
    """Convert audio to mel-spectrogram for CNN input"""
    S = librosa.feature.melspectrogram(y=y, sr=sr, n_mels=128)
    S_db = librosa.power_to_db(S, ref=np.max)
    return S_db

RNN for Sequential Music Analysis #

def create_music_rnn(sequence_length, num_features, num_classes):
    """RNN for music sequence analysis"""
    model = models.Sequential([
        layers.LSTM(128, return_sequences=True, input_shape=(sequence_length, num_features)),
        layers.Dropout(0.3),
        layers.LSTM(64, return_sequences=False),
        layers.Dropout(0.3),
        layers.Dense(32, activation='relu'),
        layers.Dense(num_classes, activation='softmax')
    ])
    return model

🎯 Traditional ML Approaches #

Feature-Based Classification #

from sklearn.ensemble import RandomForestClassifier
from sklearn.svm import SVC
from sklearn.preprocessing import StandardScaler

def extract_comprehensive_features(y, sr):
    """Extract comprehensive feature set for traditional ML"""
    features = []
    
    # Spectral features
    spectral_centroids = np.mean(librosa.feature.spectral_centroid(y=y, sr=sr))
    spectral_rolloff = np.mean(librosa.feature.spectral_rolloff(y=y, sr=sr))
    spectral_bandwidth = np.mean(librosa.feature.spectral_bandwidth(y=y, sr=sr))
    zcr = np.mean(librosa.feature.zero_crossing_rate(y))
    
    # MFCC features
    mfccs = librosa.feature.mfcc(y=y, sr=sr, n_mfcc=13)
    mfcc_means = np.mean(mfccs, axis=1)
    mfcc_stds = np.std(mfccs, axis=1)
    
    # Chroma features
    chroma = librosa.feature.chroma_stft(y=y, sr=sr)
    chroma_means = np.mean(chroma, axis=1)
    
    # Combine all features
    features.extend([spectral_centroids, spectral_rolloff, spectral_bandwidth, zcr])
    features.extend(mfcc_means)
    features.extend(mfcc_stds)
    features.extend(chroma_means)
    
    return np.array(features)

🎼 Advanced MIR Applications #

🎵 Music Recommendation System #

import pandas as pd
from sklearn.metrics.pairwise import cosine_similarity

class MusicRecommendationSystem:
    """Content-based music recommendation using audio features"""
    
    def __init__(self):
        self.features_db = None
        self.track_metadata = None
        self.scaler = StandardScaler()
        
    def extract_audio_features(self, y, sr):
        """Extract audio features for recommendation"""
        # Spectral features
        spectral_features = [
            np.mean(librosa.feature.spectral_centroid(y=y, sr=sr)),
            np.mean(librosa.feature.spectral_rolloff(y=y, sr=sr)),
            np.mean(librosa.feature.spectral_bandwidth(y=y, sr=sr)),
            np.mean(librosa.feature.zero_crossing_rate(y))
        ]
        
        # Rhythm features
        tempo, _ = librosa.beat.beat_track(y=y, sr=sr)
        rhythm_features = [tempo]
        
        # Timbral features (MFCCs)
        mfccs = librosa.feature.mfcc(y=y, sr=sr, n_mfcc=13)
        mfcc_features = list(np.mean(mfccs, axis=1))
        
        # Harmonic features (Chroma)
        chroma = librosa.feature.chroma_stft(y=y, sr=sr)
        chroma_features = list(np.mean(chroma, axis=1))
        
        return spectral_features + rhythm_features + mfcc_features + chroma_features
    
    def recommend_similar_tracks(self, query_audio, n_recommendations=5):
        """Recommend similar tracks based on audio content"""
        # Extract features from query audio
        y, sr = librosa.load(query_audio)
        query_features = self.extract_audio_features(y, sr)
        query_features_scaled = self.scaler.transform([query_features])
        
        # Calculate similarities
        similarities = cosine_similarity(query_features_scaled, self.features_db)[0]
        
        # Get top recommendations
        top_indices = np.argsort(similarities)[::-1][:n_recommendations]
        
        recommendations = []
        for idx in top_indices:
            recommendations.append({
                'track': self.track_metadata.iloc[idx]['title'],
                'artist': self.track_metadata.iloc[idx]['artist'],
                'similarity': similarities[idx]
            })
        
        return recommendations

🎭 Chord Recognition System #

class ChordRecognizer:
    """Real-time chord recognition system"""
    
    def __init__(self):
        self.chord_templates = self.create_chord_templates()
        
    def create_chord_templates(self):
        """Create chord templates based on music theory"""
        templates = {}
        
        # Chord intervals (semitones from root)
        chord_types = {
            'major': [0, 4, 7],    # Root, major third, perfect fifth
            'minor': [0, 3, 7],    # Root, minor third, perfect fifth
            'dim': [0, 3, 6],      # Diminished
            'aug': [0, 4, 8],      # Augmented
        }
        
        note_names = ['C', 'C#', 'D', 'D#', 'E', 'F', 'F#', 'G', 'G#', 'A', 'A#', 'B']
        
        for root in range(12):
            for chord_type, intervals in chord_types.items():
                chord_name = f"{note_names[root]}{chord_type if chord_type != 'major' else ''}"
                template = np.zeros(12)
                
                for interval in intervals:
                    template[(root + interval) % 12] = 1
                
                templates[chord_name] = template
        
        return templates
    
    def recognize_chords(self, y, sr, hop_length=512):
        """Recognize chord progression in audio"""
        # Use harmonic component for better chord recognition
        y_harmonic, _ = librosa.effects.hpss(y)
        
        # Extract chroma features
        chroma = librosa.feature.chroma_cqt(y=y_harmonic, sr=sr, hop_length=hop_length)
        chroma_norm = librosa.util.normalize(chroma, axis=0)
        
        chord_progression = []
        times = librosa.frames_to_time(np.arange(chroma.shape[1]), 
                                       sr=sr, hop_length=hop_length)
        
        for i in range(chroma.shape[1]):
            chroma_frame = chroma_norm[:, i]
            
            # Find best matching chord template
            best_chord = None
            best_score = -1
            
            for chord_name, template in self.chord_templates.items():
                score = np.corrcoef(chroma_frame, template)[0, 1]
                
                if not np.isnan(score) and score > best_score:
                    best_score = score
                    best_chord = chord_name
            
            chord_progression.append({
                'time': times[i],
                'chord': best_chord,
                'confidence': best_score
            })
        
        return chord_progression

🎚️ Source Separation & Audio Enhancement #

🎵 Harmonic-Percussive Separation #

def advanced_source_separation(y, sr):
    """Advanced source separation techniques"""
    
    # Basic harmonic-percussive separation
    y_harmonic, y_percussive = librosa.effects.hpss(y)
    
    # Advanced separation with different kernels
    D = librosa.stft(y)
    
    # Harmonic separation with longer horizontal kernel
    D_harmonic = librosa.decompose.hpss(D, kernel_size=(1, 31))[0]
    
    # Percussive separation with longer vertical kernel  
    D_percussive = librosa.decompose.hpss(D, kernel_size=(31, 1))[1]
    
    # Convert back to time domain
    y_harmonic_adv = librosa.istft(D_harmonic)
    y_percussive_adv = librosa.istft(D_percussive)
    
    return {
        'harmonic': y_harmonic_adv,
        'percussive': y_percussive_adv,
        'original': y
    }

# Non-negative Matrix Factorization (NMF)
def nmf_source_separation(y, sr, n_components=8):
    """Source separation using NMF"""
    # Compute magnitude spectrogram
    S = np.abs(librosa.stft(y))
    
    # Apply NMF
    W, H = librosa.decompose.decompose(S, n_components=n_components, sort=True)
    
    # Reconstruct sources
    sources = []
    for i in range(n_components):
        # Reconstruct component
        S_component = np.outer(W[:, i], H[i, :])
        
        # Apply original phase
        D = librosa.stft(y)
        phase = np.angle(D)
        
        # Reconstruct audio
        D_component = S_component * np.exp(1j * phase)
        y_component = librosa.istft(D_component)
        sources.append(y_component)
    
    return sources

📊 Evaluation & Benchmarking #

🎯 MIR Evaluation Metrics #

# Beat tracking evaluation
def evaluate_beat_tracking(reference_beats, estimated_beats):
    """Comprehensive beat tracking evaluation"""
    scores = mir_eval.beat.evaluate(reference_beats, estimated_beats)
    
    return {
        'F-measure': scores['F-measure'],
        'Cemgil': scores['Cemgil'],
        'Goto': scores['Goto'],
        'P-score': scores['P-score'],
        'Continuity': scores['Continuity']
    }

# Onset detection evaluation
def evaluate_onset_detection(reference_onsets, estimated_onsets, tolerance=0.05):
    """Evaluate onset detection performance"""
    scores = mir_eval.onset.evaluate(reference_onsets, estimated_onsets, 
                                     window=tolerance)
    
    return {
        'Precision': scores['Precision'],
        'Recall': scores['Recall'],
        'F-measure': scores['F-measure']
    }

# Chord recognition evaluation
def evaluate_chord_recognition(ref_intervals, ref_labels, est_intervals, est_labels):
    """Evaluate chord recognition performance"""
    scores = mir_eval.chord.evaluate(ref_intervals, ref_labels, 
                                     est_intervals, est_labels)
    
    return {
        'Root': scores['Root'],
        'Majmin': scores['Majmin'],
        'Sevenths': scores['Sevenths'],
        'Weighted_score': scores['Weighted_score']
    }

🚀 Real-World MIR Applications #

🎵 Music Streaming Services #

Spotify: Audio feature analysis for recommendations and playlist generation
Shazam: Audio fingerprinting for music identification
Apple Music: Genre classification and mood detection
YouTube: Content ID for copyright detection

🎼 Music Production Tools #

Auto-tune: Real-time pitch correction
Beat Detective: Automatic beat alignment
Chord Detection: DAW plugins for harmonic analysis
Stem Separation: AI-powered source separation

🎓 Music Education #

Transcription Tools: Automatic music notation generation
Practice Apps: Real-time feedback for instrument learning
Music Theory: Chord progression analysis and suggestions
Ear Training: Interval and chord recognition games

🔬 Musicology Research #

Corpus Studies: Large-scale musical analysis
Cultural Analysis: Cross-cultural music comparison
Historical Studies: Evolution of musical styles
Computational Musicology: Data-driven music research

🛠️ Best Practices & Tips #

⚡ Performance Optimization #

# Efficient audio loading
y, sr = librosa.load('audio.wav', sr=22050, mono=True)  # Downsample for speed

# Batch processing
def process_audio_batch(audio_files):
    """Process multiple audio files efficiently"""
    results = []
    
    for audio_file in audio_files:
        y, sr = librosa.load(audio_file, sr=22050)
        
        # Extract features in one pass
        features = {
            'mfcc': librosa.feature.mfcc(y=y, sr=sr),
            'chroma': librosa.feature.chroma_stft(y=y, sr=sr),
            'spectral_centroid': librosa.feature.spectral_centroid(y=y, sr=sr)
        }
        
        results.append(features)
    
    return results

# Memory-efficient processing for long audio
def process_long_audio(audio_file, chunk_size=30):
    """Process long audio files in chunks"""
    y, sr = librosa.load(audio_file)
    chunk_samples = chunk_size * sr
    
    features = []
    for i in range(0, len(y), chunk_samples):
        chunk = y[i:i + chunk_samples]
        chunk_features = extract_comprehensive_features(chunk, sr)
        features.append(chunk_features)
    
    return np.array(features)

🎯 Common Pitfalls & Solutions #

Audio Loading Issues #

# Handle different sample rates
def safe_audio_load(filename, target_sr=22050):
    """Safely load audio with error handling"""
    try:
        y, sr = librosa.load(filename, sr=target_sr)
        
        # Check for empty audio
        if len(y) == 0:
            raise ValueError("Empty audio file")
        
        # Normalize audio
        y = librosa.util.normalize(y)
        
        return y, sr
    except Exception as e:
        print(f"Error loading {filename}: {e}")
        return None, None

Feature Extraction Robustness #

def robust_feature_extraction(y, sr):
    """Extract features with error handling"""
    features = {}
    
    try:
        # MFCC with error handling
        mfccs = librosa.feature.mfcc(y=y, sr=sr, n_mfcc=13)
        if not np.any(np.isnan(mfccs)):
            features['mfcc'] = np.mean(mfccs, axis=1)
        else:
            features['mfcc'] = np.zeros(13)
    except:
        features['mfcc'] = np.zeros(13)
    
    try:
        # Chroma with error handling
        chroma = librosa.feature.chroma_stft(y=y, sr=sr)
        if not np.any(np.isnan(chroma)):
            features['chroma'] = np.mean(chroma, axis=1)
        else:
            features['chroma'] = np.zeros(12)
    except:
        features['chroma'] = np.zeros(12)
    
    return features

📚 Learning Resources #

📖 Essential Books #

“Fundamentals of Music Processing” by Meinard Müller
“An Introduction to Audio Content Analysis” by Alexander Lerch
“Music Information Retrieval” by Downie, West, Ehmann, Vincent

🌐 Online Courses & Tutorials #

CCRMA MIR Workshop (Stanford University)
Audio Signal Processing for Music Applications (Coursera)
musicinformationretrieval.com - Interactive notebooks

🔬 Research Conferences #

ISMIR - International Society for Music Information Retrieval
ICASSP - International Conference on Acoustics, Speech and Signal Processing
DAFx - International Conference on Digital Audio Effects

💻 Code Repositories #

librosa/librosa - Core audio analysis library
MTG/essentia - Comprehensive MIR toolkit
CPJKU/madmom - Beat tracking and onset detection
mir-evaluation/mir_eval - Evaluation metrics

🎵 Conclusion #

Music Information Retrieval represents the fascinating intersection of technology and artistry, enabling computers to understand and analyze the rich complexity of musical audio. With powerful Python libraries like librosa, essentia, madmom, and mir_eval, researchers and developers can build sophisticated systems for music analysis, recommendation, and understanding.

🎹 Web Audio API Speedrun

Sun, 31 May 2026 00:00:00 +0000

🎹 Web Audio API Speedrun #

Your ultra-quick guide to making sound in the browser.

🏛️ 1. The Core Concept: The Audio Context & Graph #

Everything in the Web Audio API happens inside an AudioContext. Think of it as your sound studio. Inside this studio, you connect different audio components, called AudioNodes, to create a processing pipeline, or an “audio graph.”

AudioContext: The central object that manages all audio operations.
AudioNode: A single audio processing unit. Examples include:
- Source Nodes: Generate sound (e.g., from an oscillator, an audio file).
- Effect Nodes: Modify sound (e.g., GainNode for volume, StereoPannerNode for panning).
- Destination Node: The final output, usually your computer’s speakers (audioContext.destination).

The flow is always: Source → (Zero or More Effects) → Destination

🐍 Python Image Manipulation Cheat Sheet

Sun, 31 May 2026 00:00:00 +0000

🐍 Python Image Manipulation Cheat Sheet #

A comprehensive guide to the most popular Python libraries for image manipulation: Pillow, OpenCV, and scikit-image.

🎯 Core Libraries #

Library	Strengths	Common Use Cases
`Pillow`	User-friendly, great for general-purpose tasks.	Web development, scripting, basic editing.
`OpenCV`	High-performance, extensive computer vision algorithms.	Real-time video analysis, object detection, facial recognition.
`scikit-image`	Scientific imaging, tight integration with NumPy/SciPy.	Research, medical imaging, advanced analysis.

🛠️ Installation #

# Pillow (PIL Fork)
pip install Pillow

# OpenCV
pip install opencv-python

# scikit-image
pip install scikit-image

# For NumPy integration (often a dependency, but good to have)
pip install numpy

🖼️ Pillow (PIL Fork) #

A user-friendly library for opening, manipulating, and saving many different image file formats.

🐧 Debian User Management Cheat Sheet

Sun, 31 May 2026 00:00:00 +0000

🐧 Debian User Management Cheat Sheet #

Complete guide for managing users and groups on Debian systems with best practices and security considerations.

📋 Table of Contents #

🎯 Core Concepts #

User Types #

System Users: UID < 1000, for services and daemons
Regular Users: UID ≥ 1000, for human users
Root User: UID 0, superuser with unlimited privileges

Key Files #

/etc/passwd - User account information
/etc/shadow - Encrypted passwords and aging info
/etc/group - Group definitions
/etc/gshadow - Group passwords and administrators

User Database Structure #

# /etc/passwd format:
username:x:UID:GID:GECOS:home_directory:shell

# /etc/shadow format:
username:encrypted_password:last_change:min_age:max_age:warn:inactive:expire:reserved

🛠️ Essential Tools #

Debian-Specific (Recommended) #

adduser - Interactive user creation (Debian frontend)
deluser - Safe user removal (Debian frontend)
addgroup - Group creation
delgroup - Group removal

Low-Level Tools (Universal) #

useradd - Create user accounts
userdel - Delete user accounts
usermod - Modify user accounts
groupadd - Create groups
groupdel - Delete groups
passwd - Change passwords
chsh - Change login shell
chfn - Change user information

👤 Creating Users #

Interactive User Creation (Recommended) #

# Create regular user with home directory
sudo adduser username

# Create system user
sudo adduser --system --group servicename

# Create user with specific shell
sudo adduser --shell /bin/zsh username

# Create user without home directory
sudo adduser --no-create-home username

# Create user with specific UID/GID
sudo adduser --uid 1500 --gid 1500 username

Low-Level User Creation #

# Basic user creation
sudo useradd username

# Create user with home directory and shell
sudo useradd -m -s /bin/bash username

# Create user with specific UID and groups
sudo useradd -u 1500 -g users -G sudo,audio username

# Create system user
sudo useradd --system --shell /bin/false servicename

# Create user with expiration date
sudo useradd -e 2024-12-31 tempuser

Common useradd Options #

-m, --create-home     # Create home directory
-d, --home DIR        # Specify home directory
-s, --shell SHELL     # Set login shell
-g, --gid GROUP       # Primary group
-G, --groups GROUPS   # Supplementary groups
-u, --uid UID         # User ID
-e, --expiredate DATE # Account expiration
-c, --comment GECOS   # User information
-k, --skel DIR        # Skeleton directory
-r, --system          # Create system account

✏️ Modifying Users #

Change User Properties #

# Change username
sudo usermod -l newname oldname

# Change user ID
sudo usermod -u 1600 username

# Change primary group
sudo usermod -g newgroup username

# Add user to supplementary groups
sudo usermod -aG sudo,docker username

# Change home directory
sudo usermod -d /new/home -m username

# Change login shell
sudo usermod -s /bin/zsh username
sudo chsh -s /bin/zsh username  # Alternative

# Lock/unlock user account
sudo usermod -L username  # Lock
sudo usermod -U username  # Unlock

# Set account expiration
sudo usermod -e 2024-12-31 username

# Change user information (GECOS)
sudo usermod -c "Full Name,Room,Work Phone,Home Phone" username
sudo chfn username  # Interactive alternative

Password Management #

# Change user password
sudo passwd username

# Force password change on next login
sudo passwd -e username

# Set password aging
sudo passwd -n 7 -x 90 -w 7 username  # min 7, max 90, warn 7 days

# Lock/unlock password
sudo passwd -l username  # Lock
sudo passwd -u username  # Unlock

# Delete password (dangerous)
sudo passwd -d username

🗑️ Deleting Users #

Safe User Removal (Recommended) #

# Remove user (keep home directory)
sudo deluser username

# Remove user and home directory
sudo deluser --remove-home username

# Remove user and all files
sudo deluser --remove-all-files username

# Remove user from specific group only
sudo deluser username groupname

Low-Level User Removal #

# Remove user (keep home directory)
sudo userdel username

# Remove user and home directory
sudo userdel -r username

# Force removal even if user is logged in
sudo userdel -f username

👥 Group Management #

Creating Groups #

# Create group
sudo addgroup groupname
sudo groupadd groupname  # Alternative

# Create group with specific GID
sudo groupadd -g 2000 groupname

# Create system group
sudo groupadd -r systemgroup

Managing Group Membership #

# Add user to group
sudo adduser username groupname
sudo usermod -aG groupname username  # Alternative

# Remove user from group
sudo deluser username groupname
sudo gpasswd -d username groupname  # Alternative

# List user's groups
groups username
id username

# List group members
getent group groupname

Deleting Groups #

# Delete group
sudo delgroup groupname
sudo groupdel groupname  # Alternative

# Force delete group even if it's primary group
sudo groupdel -f groupname

🔐 Password Management #

Password Policies #

# Install password quality checking
sudo apt install libpam-pwquality

# Configure in /etc/pam.d/common-password
password requisite pam_pwquality.so retry=3 minlen=8 difok=3 ucredit=-1 lcredit=-1 dcredit=-1 ocredit=-1

# Set password aging in /etc/login.defs
PASS_MAX_DAYS 90
PASS_MIN_DAYS 7
PASS_WARN_AGE 7

Password Commands #

# Generate secure password
openssl rand -base64 32
pwgen -s 16 1

# Check password expiration
sudo chage -l username

# Set password expiration
sudo chage -M 90 -m 7 -W 7 username

# Interactive password aging setup
sudo chage username

🔑 Privilege Escalation #

sudo Configuration #

# Edit sudoers file (always use visudo)
sudo visudo

# Add user to sudo group
sudo usermod -aG sudo username

# Check sudo access
sudo -l

# Run command as another user
sudo -u username command

# Preserve environment
sudo -E command

# Run shell as root
sudo -i
sudo su -

Common sudoers Entries #

# Allow user to run all commands
username ALL=(ALL:ALL) ALL

# Allow group to run specific commands
%groupname ALL=(ALL) /usr/bin/systemctl, /usr/bin/service

# Allow without password
username ALL=(ALL) NOPASSWD: ALL

# Allow specific commands on specific hosts
username hostname=(root) /usr/bin/apt, /usr/bin/dpkg

su Command #

# Switch to root
su -
su root

# Switch to another user
su - username

# Run single command as another user
su -c "command" username

📁 Configuration Files #

/etc/passwd #

# View user database
cat /etc/passwd
getent passwd

# Find specific user
getent passwd username

# List all users with UID >= 1000
awk -F: '$3 >= 1000 {print $1}' /etc/passwd

/etc/shadow #

# View password database (root only)
sudo cat /etc/shadow

# Check password status
sudo passwd -S username

/etc/group #

# View group database
cat /etc/group
getent group

# Find groups for user
groups username
id -Gn username

/etc/login.defs #

# Key settings for user creation
UID_MIN 1000
UID_MAX 60000
GID_MIN 1000
GID_MAX 60000
CREATE_HOME yes
UMASK 022
USERGROUPS_ENAB yes
ENCRYPT_METHOD SHA512

🔒 Security Best Practices #

Account Security #

# Disable unused accounts
sudo usermod -L -e 1 username

# Set strong password policies
# Edit /etc/pam.d/common-password
password requisite pam_pwquality.so minlen=12 dcredit=-1 ucredit=-1 lcredit=-1 ocredit=-1

# Enable account lockout
# Edit /etc/pam.d/common-auth
auth required pam_tally2.so deny=5 unlock_time=900

# Monitor failed logins
sudo pam_tally2 --user username

User Limits #

# Configure resource limits in /etc/security/limits.conf
* soft nproc 1000
* hard nproc 2000
* soft nofile 1024
* hard nofile 2048
@users hard core 0

Auditing Users #

# List all users
cut -d: -f1 /etc/passwd

# Find users with shell access
awk -F: '$7 !~ /nologin|false/ {print $1}' /etc/passwd

# Check for users with UID 0
awk -F: '$3 == 0 {print $1}' /etc/passwd

# Find users without passwords
sudo awk -F: '$2 == "" {print $1}' /etc/shadow

# Check for duplicate UIDs
awk -F: '{print $3}' /etc/passwd | sort | uniq -d

# List recently created users
sudo find /home -maxdepth 1 -type d -newerct "1 week ago"

🔧 Advanced Topics #

PAM Configuration #

# PAM configuration directory
ls /etc/pam.d/

# Common PAM modules
/lib/x86_64-linux-gnu/security/

# Key PAM files
/etc/pam.d/common-auth      # Authentication
/etc/pam.d/common-account   # Account management
/etc/pam.d/common-password  # Password management
/etc/pam.d/common-session   # Session management

User Environment #

# Skeleton directory for new users
ls -la /etc/skel/

# Default shell configuration
/etc/bash.bashrc
/etc/profile

# User-specific configurations
~/.bashrc
~/.profile
~/.bash_profile

Batch Operations #

# Create multiple users from file
# Format: username:password:uid:gid:gecos:home:shell
sudo newusers userlist.txt

# Change passwords in batch
# Format: username:password
sudo chpasswd < passwordlist.txt

# Mass user creation script
#!/bin/bash
for user in user1 user2 user3; do
    sudo adduser --disabled-password --gecos "" $user
    echo "$user:defaultpass" | sudo chpasswd
    sudo passwd -e $user  # Force password change
done

🚨 Troubleshooting #

Common Issues #

# User cannot login
sudo passwd -S username  # Check password status
sudo usermod -U username  # Unlock if locked

# Permission denied errors
ls -la /home/username/    # Check home directory permissions
sudo chown -R username:username /home/username/

# Group membership not taking effect
# User needs to log out and back in, or:
newgrp groupname

# Cannot delete user
sudo pkill -u username    # Kill user processes
sudo userdel -f username  # Force deletion

# Home directory not created
sudo mkhomedir_helper username

Verification Commands #

# Verify user creation
id username
getent passwd username
ls -la /home/username/

# Check group membership
groups username
id -Gn username

# Verify sudo access
sudo -l -U username

# Test user login
sudo -i -u username

Recovery Procedures #

# Reset forgotten root password (single user mode)
# 1. Boot to GRUB menu
# 2. Edit kernel parameters, add: init=/bin/bash
# 3. Mount filesystem: mount -o remount,rw /
# 4. Change password: passwd root
# 5. Reboot: exec /sbin/init

# Restore from backup
sudo cp /etc/passwd.backup /etc/passwd
sudo cp /etc/shadow.backup /etc/shadow
sudo cp /etc/group.backup /etc/group

📚 Useful Commands Reference #

Information Gathering #

whoami                    # Current user
id                       # Current user ID and groups
who                      # Logged in users
w                        # Detailed user activity
last                     # Login history
lastlog                  # Last login times
finger username          # User information (if installed)

Quick Operations #

# One-liner user creation with sudo access
sudo adduser newuser && sudo usermod -aG sudo newuser

# Create temporary user (expires in 30 days)
sudo useradd -m -e $(date -d "+30 days" +%Y-%m-%d) tempuser

# Bulk password reset
echo "username:newpassword" | sudo chpasswd

# Find all users with bash shell
grep "/bin/bash" /etc/passwd | cut -d: -f1

🎯 Best Practices Summary #

Always use adduser instead of useradd for interactive user creation
Use visudo to edit sudoers file to prevent syntax errors
Implement strong password policies with PAM modules
Regular audit user accounts and remove unused ones
Use groups for permission management instead of individual user permissions
Set appropriate resource limits to prevent abuse
Monitor user activities with logging and auditing tools
Backup user databases before making bulk changes
Test user accounts after creation or modification
Follow principle of least privilege for sudo access

man adduser - Debian user creation tool
man useradd - Low-level user creation
man usermod - User modification
man sudo - Privilege escalation
man passwd - Password management
man pam - Pluggable Authentication Modules
/usr/share/doc/adduser/ - Debian adduser documentation

This cheat sheet covers comprehensive Debian user management. Always test commands in a safe environment before applying to production systems.

🐧 Linux Shells Cheat Sheet

Sun, 31 May 2026 00:00:00 +0000

🐧 Linux Shells Cheat Sheet #

An overview of common and specialized Linux shells, from the standard Bash to the user-friendly Fish, and security-focused options like rbash and chroot.

📋 Shell Paths at a Glance #

Path	Description
`/bin/sh`	The standard command language shell. Often a symbolic link to `bash` or `dash` for POSIX compatibility.
`/bin/bash`	The Bourne Again Shell, a common interactive and scripting shell. Located in `/bin` for essential access.
`/usr/bin/bash`	Another location for Bash. On many modern systems, `/bin` is a symlink to `/usr/bin`, making them identical.
`/bin/rbash`	Restricted Bash. A version of `bash` with limited features for security.
`/usr/bin/rbash`	Another location for Restricted Bash.
`/bin/dash`	Debian Almquist Shell. A lightweight, fast, POSIX-compliant shell, often used as the default `/bin/sh`.
`/usr/bin/dash`	Another location for the Dash shell.
`/bin/bash (chrooted)`	Not a path, but `bash` running in a `chroot` jail, isolated from the main system’s file structure.

🌐 Interactive Shells #

These are the shells you typically use for day-to-day command-line work.

🐧 systemd Cheat Sheet

Sun, 31 May 2026 00:00:00 +0000

🐧 systemd Cheat Sheet #

A comprehensive guide to systemd, the init system and service manager for Linux. This sheet covers core concepts, essential commands, unit file structure, and best practices for Debian-based systems.

📜 Core Concepts #

Unit: The fundamental object systemd manages. Units represent services, mount points, devices, sockets, etc.
Unit File: A plain text file that describes a unit and its behavior. Common types include .service, .socket, .target, and .timer.
Target: A synchronization point for other units. Targets group units together and are used to bring the system to specific states (e.g., multi-user.target, graphical.target).
journald: The systemd service that handles logging. Logs are accessed via the journalctl command.

⚙️ `systemctl`: The Master Command #

The primary tool for interacting with systemd.

🐳 Docker Cheat Sheet (v28.x)

Sun, 31 May 2026 00:00:00 +0000

🐳 Docker Cheat Sheet (v28.x) #

A condensed guide to essential Docker commands, Dockerfile best practices, and Docker Compose.

📜 Core Concepts #

Image: A lightweight, standalone, executable package that includes everything needed to run a piece of software, including the code, a runtime, libraries, environment variables, and config files.
Container: A runnable instance of an image. You can create, start, stop, move, or delete a container using the Docker API or CLI.
Volume: A mechanism for persisting data generated by and used by Docker containers. Volumes are managed by Docker and are the preferred way to handle persistent storage.
Network: Provides a way to isolate containers from each other and the host machine, but also allows them to communicate with each other, the host, or external networks.
Dockerfile: A text document that contains all the commands a user could call on the command line to assemble an image.
Docker Compose: A tool for defining and running multi-container Docker applications. Uses a YAML file to configure the application’s services.

⚙️ Essential Docker CLI Commands #

General & Info #

docker version: Show Docker version information.
docker system info: Display system-wide information.
docker help: Display a list of all Docker commands.
docker <command> --help: Show help for a specific command.

Image Management #

docker build .: Build an image from a Dockerfile in the current directory.
docker build -t my-app:1.0 .: Build and tag an image.
docker images: List all local images.
docker rmi my-app:1.0: Remove an image.
docker rmi $(docker images -f "dangling=true" -q): Remove all dangling (unused) images.
docker pull nginx:latest: Pull an image from a registry (Docker Hub by default).
docker push my-repo/my-app:1.0: Push an image to a registry.
docker tag my-app:1.0 my-repo/my-app:1.0: Add a new tag to an existing image.

Container Lifecycle #

docker run -d -p 8080:80 --name my-nginx nginx: Run a container from an image in detached mode with port mapping and a name.
docker ps: List all running containers.
docker ps -a: List all containers (running and stopped).
docker stop my-nginx: Stop a running container gracefully (sends SIGTERM).
docker kill my-nginx: Stop a running container immediately (sends SIGKILL).
docker start my-nginx: Start a stopped container.
docker restart my-nginx: Restart a container.
docker rm my-nginx: Remove a stopped container.
docker rm -f my-nginx: Force-remove a running container.
docker logs my-nginx: Fetch the logs of a container.
docker logs -f my-nginx: Follow the log output in real-time.
docker exec -it my-nginx /bin/bash: Execute a command in a running container (interactive shell).

Inspection & Resource Management #

docker inspect my-nginx: Display low-level information on Docker objects (containers, images, etc.).
docker stats: Display a live stream of container(s) resource usage statistics.
docker system df: Show Docker disk usage.
docker system prune: Remove all unused data (dangling images, stopped containers, unused networks, and build cache).
docker system prune -a --volumes: Remove all unused images (not just dangling ones) and volumes.

Network Management #

docker network ls: List networks.
docker network create my-network: Create a new bridge network.
docker network inspect my-network: Display detailed information on a network.
docker network rm my-network: Remove a network.

Volume Management #

docker volume ls: List volumes.
docker volume create my-volume: Create a volume.
docker volume inspect my-volume: Display detailed information on a volume.
docker volume rm my-volume: Remove a volume.
docker volume prune: Remove all unused local volumes.

✍️ Dockerfile Best Practices #

Use .dockerignore: Exclude files and directories not needed for the build to keep the build context small and avoid leaking secrets.
Use Multi-Stage Builds: Separate build-time dependencies from runtime dependencies to create smaller, more secure final images.
Order Matters for Caching: Place instructions that change less frequently (like installing dependencies) before those that change more frequently (like copying source code).
Combine RUN instructions: Chain commands using && to reduce the number of image layers. For apt-get, combine update, install, and clean-up in one line.
```
RUN apt-get update && apt-get install -y --no-install-recommends curl && rm -rf /var/lib/apt/lists/*
```
Use Specific Base Images: Avoid latest. Use specific tags (e.g., node:18-alpine) for reproducibility and stability.
Use Minimal Base Images: Prefer smaller base images like alpine, slim, or distroless to reduce the attack surface and image size.
COPY over ADD: COPY is more transparent. Use ADD only when you need to auto-extract a tar file or fetch a remote URL.
Run as a Non-Root User: Create a dedicated user and group, and use the USER instruction to avoid running containers with root privileges.
Lint Your Dockerfile: Use tools like hadolint to check for common mistakes and apply best practices automatically.

🎼 Docker Compose (v2 Syntax) #

File: compose.yml or docker-compose.yml

👑 Advanced Python Pillow Cheat Sheet

Sun, 31 May 2026 00:00:00 +0000

👑 Advanced Python Pillow Cheat Sheet #

A deep dive into the Pillow library, focusing on advanced techniques, performance optimization, and best practices for modern image manipulation in Python.

🚀 Setup & Best Practices #

Always use a context manager: Ensures files are properly closed.
Load image data: Use im.load() before accessing pixel data for the first time to load the image data from the file.
Prefer LANCZOS for resizing: Image.Resampling.LANCZOS (formerly Image.ANTIALIAS) provides the highest quality downscaling.
Close images: Explicitly call im.close() if not using a context manager, to free up resources.

from PIL import Image, ImageFilter, ImageEnhance, ImageDraw, ImageFont, ImageOps
import numpy as np

# Best practice for opening files
try:
    with Image.open('image.jpg') as im:
        im.load() # Lazily loads the image data
        # ... process image
except FileNotFoundError:
    print("File not found.")

🎨 Modes, Bands & Color Spaces #

Understanding modes is key to advanced manipulation.

💰 ECONOMY & BANKING SYSTEM CHEAT SHEET

Sun, 31 May 2026 00:00:00 +0000

💰 ECONOMY & BANKING SYSTEM CHEAT SHEET #

Ultra-Condensed Enlightenment Guide - CORRECTED VERSION

🏦 CORE BANK ARCHITECTURE #

🎯 Bank Module: redbot.core.bank (1088 lines, enterprise-grade banking system)
🔧 Storage Backend: Red’s Config API with JSON/PostgreSQL support
📊 Account Types: Global (cross-guild) or Per-Guild banking modes
🎨 Balance Management: Integer-only balances (no float precision issues)
🔄 Cache System: Intelligent caching for default/max balances and bank names
🛡️ Transaction Safety: Atomic operations with rollback on exceptions
📦 Account Model: Account class with name, balance, created_at attributes
🎯 Time Encoding: Unix timestamp encoding for account creation tracking

💰 ESSENTIAL BANK API FUNCTIONS #

Core Balance Operations #

# Primary balance functions - EXACT signatures from bank.py
await bank.get_balance(member: discord.Member) -> int
await bank.set_balance(member: Union[discord.Member, discord.User], amount: int) -> int
await bank.can_spend(member: discord.Member, amount: int) -> bool
await bank.get_account(member: Union[discord.Member, discord.User]) -> Account

# Transaction functions with error handling
await bank.withdraw_credits(member: discord.Member, amount: int) -> int
await bank.deposit_credits(member: discord.Member, amount: int) -> int
await bank.transfer_credits(
    from_: Union[discord.Member, discord.User],
    to: Union[discord.Member, discord.User], 
    amount: int
) -> int  # Returns new balance of recipient

Bank Configuration Functions #

# Global vs Guild modes
await bank.is_global() -> bool
await bank.set_global(global_: bool) -> bool

# Bank/Currency naming
await bank.get_bank_name(guild: discord.Guild = None) -> str
await bank.set_bank_name(name: str, guild: discord.Guild = None) -> str
await bank.get_currency_name(guild: discord.Guild = None) -> str  
await bank.set_currency_name(name: str, guild: discord.Guild = None) -> str

# Balance limits and defaults
await bank.get_max_balance(guild: discord.Guild = None) -> int
await bank.set_max_balance(amount: int, guild: discord.Guild = None) -> int
await bank.get_default_balance(guild: discord.Guild = None) -> int
await bank.set_default_balance(amount: int, guild: discord.Guild = None) -> int

🏆 LEADERBOARD & ANALYTICS #

Leaderboard Functions #

# Get ranked user list
await bank.get_leaderboard(
    positions: int = None, 
    guild: discord.Guild = None
) -> List[tuple]  # Returns [(user_id, raw_account), ...]

# Find user position
await bank.get_leaderboard_position(
    member: Union[discord.User, discord.Member]
) -> Union[int, None]

Data Management #

# Administrative functions
await bank.wipe_bank(guild: Optional[discord.Guild] = None) -> None
await bank.bank_prune(
    bot: Red, 
    guild: discord.Guild = None, 
    user_id: int = None
) -> None

⚡ TRANSACTION DECORATOR SYSTEM #

@cost Decorator - Command Cost Management #

from redbot.core.bank import cost, AbortPurchase

# Automatic cost deduction with refund on failure
@bank.cost(100)  # Costs 100 credits
@commands.command()
async def gamble(self, ctx):
    # Credits withdrawn automatically before command execution
    try:
        # Your command logic here
        if success:
            return await ctx.send("You won!")
        else:
            raise AbortPurchase()  # Refunds the cost silently
    except SomeError:
        # Credits auto-refunded on any exception
        raise

# Works on both commands and async functions
@bank.cost(50)
async def some_function(ctx):
    # Function implementation
    pass

🚨 ERROR HANDLING & EXCEPTIONS #

Bank-Specific Exception Types #

from redbot.core.errors import BalanceTooHigh, BankPruneError
from redbot.core.bank import AbortPurchase

# Handle banking errors properly
try:
    await bank.deposit_credits(member, 999999999)
except BalanceTooHigh as e:
    # User would exceed max balance
    await ctx.send(f"Balance limit exceeded: {e}")

try:
    await bank.withdraw_credits(member, amount)
except ValueError as e:
    # Insufficient funds or invalid amount (amount <= 0)
    await ctx.send(f"Transaction failed: {e}")
except TypeError as e:
    # Amount not an integer
    await ctx.send(f"Invalid amount type: {e}")

# Intentional refund in @cost decorated functions
if should_refund:
    raise AbortPurchase()  # Consumed by decorator, credits returned

🔧 BANK OPERATION PATTERNS #

Safe Transaction Patterns #

# Always check before spending
if await bank.can_spend(user, cost):
    await bank.withdraw_credits(user, cost)
    # Proceed with operation
else:
    await ctx.send("Insufficient funds!")

# Transfer with validation
try:
    new_balance = await bank.transfer_credits(sender, receiver, amount)
    await ctx.send(f"Transfer complete! {receiver.display_name} now has {new_balance}")
except ValueError:
    await ctx.send("Transfer failed - insufficient funds or invalid amount")
except BalanceTooHigh:
    await ctx.send("Receiver balance would exceed maximum")
except RuntimeError:
    await ctx.send("Bank operation error - check guild context")

Bank Mode Management #

# Check bank mode before operations
if await bank.is_global():
    # Global bank - works across all guilds
    balance = await bank.get_balance(member)
else:
    # Guild-specific bank - requires guild context
    if not ctx.guild:
        return await ctx.send("No guild bank in DMs!")
    balance = await bank.get_balance(member)

🎮 INTEGRATION WITH GAME SYSTEMS #

Economy Game Development #

class SlotMachine:
    @bank.cost(10)  # 10 credits to play
    @commands.command()
    async def slots(self, ctx):
        # Game logic here - cost already deducted
        if win:
            winnings = calculate_winnings()
            await bank.deposit_credits(ctx.author, winnings)
            return await ctx.send(f"You won {winnings} credits!")
        # Loss = credits already deducted by decorator

# Manual economy integration
async def lottery_entry(self, ctx, amount: int):
    if not await bank.can_spend(ctx.author, amount):
        return await ctx.send("Not enough credits!")
    
    await bank.withdraw_credits(ctx.author, amount)
    # Add to lottery pool
    self.lottery_pool += amount

📊 BANK CONFIGURATION BEST PRACTICES #

Initial Bank Setup #

# Set up new guild bank
await bank.set_global(False)  # Guild-specific mode
await bank.set_bank_name("Guild Treasury", guild)
await bank.set_currency_name("Gold Coins", guild)
await bank.set_default_balance(100, guild)  # Starting balance
await bank.set_max_balance(1000000, guild)  # Balance cap

Economy Balancing #

# Get economy statistics
leaderboard = await bank.get_leaderboard(10, guild)  # Top 10
total_wealth = sum(account[1]['balance'] for account in leaderboard)

# Admin commands for economy management
@commands.admin()
async def economy_reset(self, ctx):
    await bank.wipe_bank(ctx.guild)
    await ctx.send("Guild economy reset!")

🛡️ SECURITY & VALIDATION #

Input Validation Patterns #

# Amount validation (bank does this automatically)
# bank functions raise TypeError for non-int amounts
# bank functions raise ValueError for amounts <= 0

# Member validation in global vs guild banks
async def validate_bank_access(member, guild=None):
    if await bank.is_global():
        return True  # Global bank = anyone can access
    else:
        return guild is not None  # Guild bank = need guild context

Rate Limiting Economy Commands #

@commands.cooldown(1, 30, commands.BucketType.user)  # 30s cooldown
@bank.cost(50)
@commands.command()
async def daily_bonus(self, ctx):
    bonus = 100
    await bank.deposit_credits(ctx.author, bonus)
    await ctx.send(f"Daily bonus: {bonus} credits!")

🔍 DEBUGGING & MONITORING #

Bank State Inspection #

# Debug bank configuration
bank_mode = "Global" if await bank.is_global() else "Guild-specific"
currency = await bank.get_currency_name(guild)
max_bal = await bank.get_max_balance(guild)
default_bal = await bank.get_default_balance(guild)

await ctx.send(f"Bank: {bank_mode} | Currency: {currency} | Max: {max_bal}")

# Account debugging
account = await bank.get_account(member)
await ctx.send(f"Account: {account.name} | Balance: {account.balance} | Created: {account.created_at}")

🔑 CRITICAL IMPLEMENTATION DETAILS #

Constants & Limits #

# From bank.py implementation
_MAX_BALANCE = 2 ** 63 - 1  # Maximum possible balance
# Default balance: 0
# Default max balance: 1000000
# Account.name = member.display_name
# Account.created_at = datetime object from encoded timestamp

Function Return Behaviors #

# withdraw_credits() returns new balance after withdrawal
# deposit_credits() returns new balance after deposit  
# transfer_credits() returns recipient's new balance
# set_balance() returns the newly set balance
# All balance functions return int, never float

💰 Master Red-DiscordBot’s banking system with 100% accurate API implementation patterns!

📊 CONFIGURATION MANAGEMENT SYSTEM CHEAT SHEET

Sun, 31 May 2026 00:00:00 +0000

📊 CONFIGURATION MANAGEMENT SYSTEM CHEAT SHEET #

Ultra-Condensed Enlightenment Guide - CORRECTED VERSION

🗄️ CONFIG API CORE SYSTEM #

🎯 Entry Point: Config.get_conf(self, identifier=unique_int, force_registration=True)
🔧 File Location: redbot/core/config.py (1544 lines of sophisticated configuration management)
📦 Core Classes: Config, Value, Group, ConfigValue, ConfigGroup
🎨 Metaclass: ConfigMeta ensures singleton pattern per cog/identifier combination
🔄 Driver Architecture: BaseDriver → JSONDriver (default), PostgreSQLDriver (enterprise)
🛡️ Thread Safety: Asyncio locks per value for concurrent access protection
📊 Weak References: Intelligent caching with automatic garbage collection
🎯 Error Handling: Comprehensive validation and error recovery mechanisms
🔧 Migration: Built-in schema versioning and data migration support
📋 Debugging: Rich debugging and introspection capabilities

🎚️ DATA SCOPE HIERARCHY MASTERY #

# Scope Constants and Usage (Red 3.5+)
GLOBAL = 0      # Bot-wide settings (one instance across all guilds)
GUILD = 1       # Per-server settings (guild.id)
CHANNEL = 2     # Per-channel settings (channel.id)
ROLE = 3        # Per-role settings (role.id)
USER = 4        # Per-user global settings (user.id)
MEMBER = 5      # Per-member guild settings (guild.id, user.id)
CUSTOM = 6      # Custom identifier settings (any_id)

# Registration Patterns with force_registration (RECOMMENDED)
self.config = Config.get_conf(self, identifier=12345, force_registration=True)

self.config.register_global(setting=default_value)
self.config.register_guild(guild_setting=default_value)
self.config.register_channel(channel_setting=default_value)
self.config.register_role(role_setting=default_value)
self.config.register_user(user_setting=default_value)
self.config.register_member(member_setting=default_value)
self.config.custom("CUSTOM_SCOPE", custom_id).register(custom_setting=default)

💾 BACKEND DRIVER SYSTEM #

📄 JSON Driver (Default) #

🎯 Storage: Human-readable JSON files in bot’s data directory
🔧 Performance: Optimized for small to medium datasets (< 10MB per scope)
📊 Structure: Hierarchical file organization by scope and identifier
🎨 Debugging: Easy inspection and manual editing for development
🔄 Backup: Simple file-based backup and restore procedures
🛡️ Atomicity: Atomic writes with temporary files for data integrity
📦 Compression: Optional gzip compression support for large datasets
🎯 Migration: JSON-to-JSON migration for schema changes and upgrades

🐘 PostgreSQL Driver (Enterprise) #

🎯 Storage: Professional PostgreSQL database backend for production
🔧 Performance: Optimized for massive datasets and high concurrency
📊 ACID: Full ACID compliance for data integrity guarantees
🎨 Scalability: Handles enterprise-scale deployments efficiently
🔄 Clustering: Database clustering and replication support
🛡️ Security: Database-level security, encryption, and access controls
📦 Monitoring: Professional database monitoring integration support
🎯 Migration: SQL-based schema migration system with versioning

🔄 VALUE & GROUP CLASS ARCHITECTURE #

Value Class (Primitives) #

# Value for simple data types (str, int, float, bool, list)
setting = await self.config.guild(guild).setting()
await self.config.guild(guild).setting.set(new_value)
await self.config.guild(guild).setting.clear()

# Value with default fallback handling
value = await self.config.guild(guild).setting() or "default"

# Atomic operations for thread safety
current = await self.config.guild(guild).counter()
await self.config.guild(guild).counter.set(current + 1)

Group Class (Containers) #

# Group for complex nested data structures
async with self.config.guild(guild).nested_data() as data:
    data["key"] = "value"
    data["nested"] = {"deep": "setting"}
    data["list"] = [1, 2, 3]

# Group manipulation without context manager
group = self.config.guild(guild).group_name
await group.key.set("value")
nested = await group.nested.all()

# Raw access for deep nesting
await self.config.guild(guild).data.set_raw("nested", "deep", "key", value=42)
deep_value = await self.config.guild(guild).data.get_raw("nested", "deep", "key", default=0)

🔐 CONCURRENCY & LOCK MANAGEMENT #

🎯 Lock Granularity: Per-value locks prevent data races and corruption
🔧 Async Context: async with pattern for safe modifications
📊 Deadlock Prevention: Careful lock ordering algorithms and timeout handling
🎨 Performance: Minimal lock contention through granular locking strategy
🔄 Timeout Handling: Configurable lock timeouts to prevent hanging
🛡️ Error Recovery: Automatic lock cleanup on exceptions and crashes
📦 Resource Management: Proper lock resource cleanup and monitoring
🎯 Debugging: Lock state monitoring and debugging capabilities
🔧 Optimization: Lock-free operations where thread safety isn’t required
📊 Metrics: Lock performance and contention tracking for optimization

📝 REGISTRATION SYSTEM MASTERY #

# Force Registration (Red 3.5+ BEST PRACTICE)
self.config = Config.get_conf(
    self, 
    identifier=1234567890,
    force_registration=True  # Prevents unregistered key errors
)

self.config.register_global(
    prefix="!",
    color=0xFF0000,
    features={"music": True, "economy": False}
)

# Structured Default Value Patterns
default_guild = {
    "enabled": True,
    "prefix": "!",
    "admin_roles": [],
    "settings": {
        "automod": False,
        "logging": True,
        "channel_ids": {
            "modlog": None,
            "general": None
        }
    },
    "features": {
        "welcome": False,
        "autorole": None,
        "level_system": {
            "enabled": False,
            "multiplier": 1.0
        }
    }
}
self.config.register_guild(**default_guild)

# Custom Scope Registration with Identifiers
self.config.custom("ECONOMY", user_id).register(
    balance=0,
    daily_last=None,
    transactions=[],
    settings={"notifications": True}
)

# Member-specific data (guild + user combination)
self.config.register_member(
    xp=0,
    level=1,
    warnings=[],
    notes=""
)

🗂️ NESTED DATA MANAGEMENT #

Deep Nesting Patterns #

# Safe nested modification with context manager
async with self.config.guild(guild).complex_data() as data:
    if "users" not in data:
        data["users"] = {}
    if str(user.id) not in data["users"]:
        data["users"][str(user.id)] = {"points": 0, "level": 1}
    data["users"][str(user.id)]["points"] += 10
    
    # Nested structure validation
    if "statistics" not in data:
        data["statistics"] = {"daily": {}, "weekly": {}}

# Nested value access using raw methods
points = await self.config.guild(guild).complex_data.get_raw(
    "users", str(user.id), "points", default=0
)
await self.config.guild(guild).complex_data.set_raw(
    "users", str(user.id), "points", value=100
)

# Multi-level nesting with error handling
try:
    daily_stats = await self.config.guild(guild).statistics.get_raw(
        "daily", str(datetime.now().date()), default={}
    )
except KeyError:
    # Handle missing nested keys gracefully
    daily_stats = {}

Group Hierarchy Operations #

# Get all data at specific scope levels
all_guild_data = await self.config.guild(guild).all()
all_user_data = await self.config.user(user).all()
all_global_data = await self.config.all()

# Clear operations for different scopes
await self.config.guild(guild).clear()                 # Clear one guild
await self.config.clear_all_guilds()                  # Clear all guilds
await self.config.clear_all_users()                   # Clear all users
await self.config.clear_all_channels()                # Clear all channels

# Bulk operations for data management
all_guilds_data = await self.config.all_guilds()
all_users_data = await self.config.all_users()
all_members_data = await self.config.all_members()

# Iteration over all data
async for guild_id, guild_data in (await self.config.all_guilds()).items():
    guild = self.bot.get_guild(guild_id)
    if guild:
        await self.process_guild_data(guild, guild_data)

🧹 DATA CLEANUP & MAINTENANCE #

# Scope-specific cleanup operations
await self.config.guild(guild).clear()                 # Clear one guild's data
await self.config.clear_all_guilds()                  # Clear all guild data
await self.config.clear_all_users()                   # Clear all user data
await self.config.clear_all_channels()                # Clear all channel data

# Selective cleanup with validation
async for guild_id, guild_data in (await self.config.all_guilds()).items():
    guild = self.bot.get_guild(guild_id)
    if not guild:  # Bot left guild
        await self.config.guild_from_id(guild_id).clear()
        log.info(f"Cleaned up data for left guild: {guild_id}")

# User data cleanup for inactive users
async for user_id, user_data in (await self.config.all_users()).items():
    user = self.bot.get_user(user_id)
    if not user:  # User not in cache
        try:
            user = await self.bot.fetch_user(user_id)
        except discord.NotFound:
            await self.config.user_from_id(user_id).clear()
            log.info(f"Cleaned up data for deleted user: {user_id}")

# Data validation and repair
all_data = await self.config.all()
if await self.validate_config_data(all_data):
    log.info("Configuration data validation passed")
else:
    log.warning("Configuration data validation failed, attempting repair")
    await self.repair_config_data()

💨 CACHING & PERFORMANCE #

🎯 Weak Reference Cache: Automatic memory management with weak references
🔧 Cache Invalidation: Smart cache invalidation on data changes and updates
📊 Batch Operations: Optimized bulk read/write operations for performance
🎨 Lazy Loading: Load data only when accessed (on-demand loading)
🔄 Connection Pooling: Database connection pooling for PostgreSQL driver
🛡️ Cache Coherence: Multi-instance cache synchronization for clusters
📦 Memory Efficiency: Minimal memory footprint through weak reference usage
🎯 Performance Monitoring: Built-in performance metrics and profiling
🔧 Optimization: Query optimization for complex nested data structures
📊 Profiling: Built-in profiling and performance analysis tools

🔐 DATA INTEGRITY & VALIDATION #

# Type validation with error handling
async def validate_setting(self, value):
    if not isinstance(value, (int, float)) or value < 0:
        raise ValueError("Setting must be non-negative number")
    if value > 1000000:
        raise ValueError("Setting value too large")
    return value

# Schema migration with version tracking
async def migrate_data(self):
    version = await self.config.schema_version()
    if version < "2.0.0":
        log.info("Migrating from version 1.x to 2.0.0")
        # Migrate from version 1 to 2
        old_data = await self.config.all()
        new_data = await self.convert_schema_v1_to_v2(old_data)
        await self.config.clear()
        await self.config.set(new_data)
        await self.config.schema_version.set("2.0.0")

# Data consistency checks with repair
async def check_data_consistency(self):
    issues_found = []
    
    # Check guild data consistency
    for guild_id, data in (await self.config.all_guilds()).items():
        guild = self.bot.get_guild(guild_id)
        if not guild:
            issues_found.append(f"Guild {guild_id} not found")
            await self.config.guild_from_id(guild_id).clear()
            continue
            
        # Validate required keys
        required_keys = ["enabled", "settings"]
        for key in required_keys:
            if key not in data:
                issues_found.append(f"Missing key '{key}' in guild {guild_id}")
                await self.repair_guild_data(guild_id, key)
    
    return issues_found

# Atomic operations for data integrity
async def atomic_increment(self, user):
    """Atomically increment user's counter"""
    async with self.config.user(user).counter.get_lock():
        current = await self.config.user(user).counter()
        await self.config.user(user).counter.set(current + 1)
        return current + 1

⚡ QUICK CONFIG REFERENCE #

# Essential Config Setup (Red 3.5+ Best Practices)
self.config = Config.get_conf(
    self, 
    identifier=1234567890,
    force_registration=True  # HIGHLY RECOMMENDED
)
self.config.register_global(setting="default")
self.config.register_guild(guild_setting="default")

# Common Operations
value = await self.config.guild(guild).setting()          # Get value
await self.config.guild(guild).setting.set(value)        # Set value
await self.config.guild(guild).setting.clear()           # Clear value

# Nested Data with Context Manager
async with self.config.guild(guild).nested() as data:     # Modify nested
    data["key"] = "value"
    data["structure"] = {"nested": True}

# Bulk Operations
all_data = await self.config.all_guilds()                 # Get all guilds
await self.config.clear_all_guilds()                      # Clear all guilds

# Custom Scopes
custom = self.config.custom("SCOPE", identifier)          # Access custom scope
await custom.setting.set(value)                           # Use like any scope

# Raw Access for Deep Nesting
await self.config.guild(guild).data.set_raw("a", "b", "c", value=42)
value = await self.config.guild(guild).data.get_raw("a", "b", "c", default=0)

# Data Types Supported
await self.config.setting.set("string")                   # String
await self.config.setting.set(42)                         # Integer
await self.config.setting.set(3.14)                       # Float
await self.config.setting.set(True)                       # Boolean
await self.config.setting.set([1, 2, 3])                  # List
await self.config.setting.set({"key": "value"})           # Dictionary

📊 Configuration is the persistent memory of Red’s ecosystem. Master these patterns for bulletproof data management with 100% accuracy!

📚 Python Image Manipulation Cheat Sheets

Sun, 31 May 2026 00:00:00 +0000

📚 Python Image Manipulation Cheat Sheets #

Welcome to the comprehensive collection of cheat sheets for Python image manipulation. This repository provides a series of guides ranging from a general overview to advanced, in-depth documentation for the most popular Python imaging libraries.

Whether you’re a beginner looking to get started or an experienced developer seeking advanced techniques and best practices, these guides are designed to be a valuable resource.

📦 NPX (Node Package eXecute) on Debian Cheat Sheet

Sun, 31 May 2026 00:00:00 +0000

📦 NPX (Node Package eXecute) on Debian Cheat Sheet #

Complete guide for using NPX package runner on Debian systems with best practices and security considerations.

📋 Table of Contents #

🎯 What is NPX #

NPX (Node Package eXecute) is a package runner tool that comes bundled with npm 5.2+ and allows you to execute npm packages without installing them globally.

🔧 VSCode settings.json Cheat Sheet

Sun, 31 May 2026 00:00:00 +0000

🔧 VSCode settings.json Cheat Sheet #

📍 Overview #

VSCode settings.json files control editor behavior through JSON configuration. There are two types:

User Settings: Global settings that apply to all VSCode instances
Workspace Settings: Project-specific settings that override user settings

📂 File Locations #

User Settings #

Windows: %APPDATA%\Code\User\settings.json
macOS: $HOME/Library/Application Support/Code/User/settings.json
Linux: $HOME/.config/Code/User/settings.json

Workspace Settings #

Location: .vscode/settings.json in your project root
Purpose: Share project-specific settings via version control
Priority: Overrides user settings for that workspace

🎯 Accessing Settings #

Command Palette (Ctrl+Shift+P) #

Preferences: Open User Settings (JSON)
Preferences: Open Workspace Settings (JSON)
Preferences: Open Settings (UI)

Keyboard Shortcuts #

Settings UI: Ctrl+, (Cmd+, on Mac)
Direct JSON: Use command palette

vscode://settings/<settingName>

Example: vscode://settings/workbench.colorTheme

🔬 Advanced Python scikit-image Cheat Sheet

Sun, 31 May 2026 00:00:00 +0000

🔬 Advanced Python scikit-image Cheat Sheet #

A guide to advanced image processing and analysis with scikit-image, focusing on scientific applications and best practices.

⚙️ Core Concepts & Data Types #

NumPy-centric: scikit-image operates directly on NumPy arrays, making it seamless to integrate with the scientific Python ecosystem.
Data Type Conventions: scikit-image has specific conventions for data types and ranges. It’s crucial to use the provided utility functions for conversions to avoid unexpected results.
- uint8: 0 to 255
- float: -1 to 1 (or 0 to 1 for some functions). Use skimage.img_as_float() and skimage.img_as_ubyte().

import skimage
from skimage import data, io
from skimage.util import img_as_float, img_as_ubyte

# Load a sample image (returns a NumPy array)
image = data.camera()

# Convert to float for processing
image_float = img_as_float(image)

print(f'Original dtype: {image.dtype}, Range: ({image.min()}, {image.max()})')
print(f'Float dtype: {image_float.dtype}, Range: ({image_float.min():.2f}, {image_float.max():.2f})')

Colorspaces: Use the skimage.color module for robust colorspace conversions (e.g., rgb2gray, rgb2hsv).

from skimage.color import rgb2gray, rgb2hsv

# Load a color image
color_image = data.astronaut()

# Convert to grayscale
gray_image = rgb2gray(color_image)

# Convert to HSV
hsv_image = rgb2hsv(color_image)

🧼 Image Filtering & Preprocessing #

Local & Non-Local Filters #

Local Filters: Operate on a neighborhood of pixels.
- filters.gaussian(): For smoothing and noise reduction.
- filters.sobel(): For edge detection (gradient magnitude).
- filters.median(): Excellent for salt-and-pepper noise.
Non-Local Filters: Use a larger portion of the image.
- restoration.denoise_nl_means(): Non-local means denoising, great for preserving texture.
- restoration.denoise_tv_chambolle(): Total variation denoising, good for piecewise-constant images.

from skimage import filters
from skimage import restoration

# Gaussian filter
smoothed_image = filters.gaussian(image_float, sigma=1.0)

# Sobel edge detection
edges = filters.sobel(image_float)

# Total Variation Denoising
denoised_image = restoration.denoise_tv_chambolle(image_float, weight=0.1)

Mathematical Morphology #

Used for probing and shaping images, typically on binary (boolean) images.

🔬 librosa Quick-Start Cheat Sheet

Sun, 31 May 2026 00:00:00 +0000

🔬 librosa Quick-Start Cheat Sheet #

An epically overpowered, complete, precise, condensed, over-emojified, logically structured, clean, genius, practical, enticing, and easy-to-follow markdown quick-start cheat sheet for librosa.

🚀 Quick Start #

📦 Installation #

Install librosa using your preferred package manager:

_# Using pip
_pip install librosa

_# Using conda
_conda install -c conda-forge librosa

▶️ Basic Usage: Beat Tracking #

librosa excels at analyzing audio. Here’s a quick taste:

🚀 Advanced Python OpenCV Cheat Sheet

Sun, 31 May 2026 00:00:00 +0000

🚀 Advanced Python OpenCV Cheat Sheet #

A guide to advanced computer vision with OpenCV, focusing on performance, powerful techniques, and best practices.

⚙️ Setup & Core Concepts #

Color Order: OpenCV uses BGR order by default, while most other libraries (Pillow, Matplotlib) use RGB. Always be mindful of color space conversions.
NumPy Backend: OpenCV images are NumPy arrays. This allows for powerful, efficient, and simple slicing and manipulation.
Performance: Use cv2.setUseOptimized(True) to enable optimized code paths.

import cv2
import numpy as np

# Load image
img = cv2.imread('image.jpg')

# Check if image loaded correctly
if img is None:
    print("Error: Could not read image.")
else:
    # Get properties
    height, width, channels = img.shape
    print(f'Dimensions: {width}x{height}, Channels: {channels}')

# BGR to RGB conversion for display with other libs
img_rgb = cv2.cvtColor(img, cv2.COLOR_BGR2RGB)

# Grayscale conversion
gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)

🎨 Image Processing & Enhancement #

Blurring & Filtering #

Gaussian Blur: For reducing high-frequency noise.
Median Blur: Effective against salt-and-pepper noise.
Bilateral Filtering: Preserves edges while reducing noise.

# Gaussian Blur (kernel size must be odd)
gaussian = cv2.GaussianBlur(img, (5, 5), 0)

# Median Blur (kernel size must be odd)
median = cv2.medianBlur(img, 5)

# Bilateral Filter
bilateral = cv2.bilateralFilter(img, 9, 75, 75)

Thresholding #

Used to segment parts of an image.

🚀 Groq + Gradio: Ultimate AI Showcase Demo

Sun, 31 May 2026 00:00:00 +0000

🚀 Groq + Gradio: Ultimate AI Showcase Demo #

The most genius way to showcase Groq’s blazing-fast AI capabilities through interactive Gradio demos! This comprehensive guide covers building demos for reasoning, vision, audio, tool calling, and parameter experimentation.

🎯 Quick Setup #

import gradio as gr
from groq import Groq
import base64
import json
import os

# Initialize Groq client
client = Groq(api_key=os.getenv("GROQ_API_KEY"))

🧠 Demo 1: Reasoning Playground #

Interactive demo for testing different reasoning models and parameters:

🚀 Groq API Cheat Sheet

Sun, 31 May 2026 00:00:00 +0000

🚀 Groq API Cheat Sheet #

Welcome to the Groq API cheat sheet! This guide provides a comprehensive overview of how to use the Groq API for ultra-fast large language model (LLM) inference. Whether you’re building a chatbot, a content generation tool, or any other application that requires real-time language processing, Groq offers the speed and performance you need.

🔑 Getting Started #

1. Get Your API Key #

First, you’ll need a Groq API key. You can get one by signing up on the Groq Console.

🚀 HugDown Complete Guide

Sun, 31 May 2026 00:00:00 +0000

🚀 HugDown Complete Guide #

Ultra-comprehensive documentation for the HugDown markdown transformation toolkit

📋 Overview #

HugDown is a comprehensive toolkit transforming markdown into multiple formats with professional theming, AI styling, and enterprise features.

Core Philosophy #

DRY Principle: Single source markdown, multiple outputs
AI-First Design: Intelligent theme selection
Performance: Caching, async, parallel execution
Accessibility: WCAG AA compliant
Multi-Interface: CLI, API, programmatic

Project Structure #

hugdown/
├── beautysheet/    # FastAPI PDF converter with WebSocket
├── quicksheet/     # CLI converter with AI caching
├── hugmark/        # Hugo + PDF hybrid
└── hugo.md         # Hugo quick-start guide

🏗️ Architecture #

Component Matrix #

Component	Stack	Use Case	Interface	Status
BeautySheet	Python + FastAPI + WeasyPrint	Server batch PDF	REST + WebSocket	🟡 Alpha
QuickSheet	Python + Click + AI	Local intelligent PDF	CLI	🟡 Alpha
HugMark	Hugo + Node + Puppeteer	Static site + PDF	Web + CLI	🟢 Stable

System Overview #

graph TB
    subgraph Input
        MD[📝 Markdown Files]
    end
    
    subgraph Processing
        BS[🎨 BeautySheet<br/>FastAPI Server]
        QS[⚡ QuickSheet<br/>Local CLI]
        HM[🌐 HugMark<br/>Hugo + PDF]
    end
    
    subgraph Output
        PDF1[📄 Server PDF]
        PDF2[📄 Local PDF]
        WEB[🌍 Static Site]
        PDF3[📄 Site PDFs]
    end
    
    MD --> BS --> PDF1
    MD --> QS --> PDF2
    MD --> HM --> WEB
    HM --> PDF3
    
    style BS fill:#e1f5ff
    style QS fill:#fff3e0
    style HM fill:#f3e5f5

Data Flow Architecture #

sequenceDiagram
    participant User
    participant Tool
    participant Converter
    participant AI
    participant Cache
    participant Output
    
    User->>Tool: Submit Markdown
    Tool->>Cache: Check Cache
    alt Cache Hit
        Cache-->>Tool: Return Cached
    else Cache Miss
        Tool->>AI: Analyze Content
        AI-->>Tool: Theme Recommendation
        Tool->>Converter: Process with Theme
        Converter->>Converter: MD→HTML→PDF
        Converter-->>Tool: Generated PDF
        Tool->>Cache: Store Result
    end
    Tool-->>Output: Deliver PDF
    Output-->>User: Download

🔧 BeautySheet #

Enterprise PDF generation service with real-time tracking

🚀 Hugo Speedrun on Debian

Sun, 31 May 2026 00:00:00 +0000

🚀 Hugo Speedrun on Debian #

Your ultra-quick guide to hosting markdown files with Hugo.

🛠️ 1. Installation #

First, get the necessary tools. We’ll grab the latest Hugo Extended version from GitHub.

# Install Git
sudo apt update && sudo apt install git -y

# Find latest Hugo extended .deb file from https://github.com/gohugoio/hugo/releases
# Example for v0.128.0:
wget https://github.com/gohugoio/hugo/releases/download/v0.128.0/hugo_extended_0.128.0_linux-amd64.deb

# Install the package
sudo dpkg -i hugo_extended_0.128.0_linux-amd64.deb

# Verify installation
hugo version

🌐 2. Create a New Site #

Now, let’s scaffold a new Hugo project.

🚀 Integrating Groq into the chatgpt-md Obsidian Plugin

Sun, 31 May 2026 00:00:00 +0000

🚀 Integrating Groq into the chatgpt-md Obsidian Plugin #

This guide will walk you through the process of integrating the ultra-fast Groq API into the chatgpt-md Obsidian plugin. By following these steps, you’ll be able to leverage Groq’s performance directly within Obsidian.

Prerequisites #

You have a working chatgpt-md plugin development environment set up.
You have a Groq API key, which you can get from the Groq Console.

1. Create a New `GroqService.ts` File #

The first step is to create a new service for Groq. The easiest way to do this is to copy the existing OpenAiService.ts and adapt it for Groq.

Automation Strategy: Perfect Video-to-Music Synchronization

Sun, 31 May 2026 00:00:00 +0000

Automation Strategy: Perfect Video-to-Music Synchronization #

This cheat sheet provides a comprehensive guide to automating the process of synchronizing video clips to music or audio tracks. It covers two primary strategies: rhythm-based synchronization for music videos and content-based synchronization for speech-driven content.

Core Concepts #

Rhythm-Based Synchronization: This method analyzes the audio track to identify rhythmic features like beats, onsets (the beginning of a musical note or sound), and tempo. Video clips are then cut and ordered to align with these rhythmic events, creating a dynamic and visually engaging music video.

cheat Sheets to do

Sun, 31 May 2026 00:00:00 +0000

cheat Sheets to do #

pydantic

Mermaid.js Comprehensive Cheat Sheet

Sun, 31 May 2026 00:00:00 +0000

Mermaid.js Comprehensive Cheat Sheet #

A condensed guide to all Mermaid.js chart types, with syntax, options, and illustrative examples.

1. Flowchart #

Used for creating flow diagrams.

Syntax #

flowchart TD
    A[Start] --> B{Is it?};
    B -- Yes --> C[OK];
    C --> D[End];
    B -- No --> E[Not OK];
    E --> D;

Nodes: id[text], id(text), id((text)), id>text], id{text}
Links: -->, ---, -.->, -- text -->
Direction: TD (top-down), LR (left-right), etc.
Subgraphs:

flowchart TD
    subgraph one
        a1-->a2
    end
    subgraph two
        b1-->b2
    end
    c1-->c2

2. Sequence Diagram #

Illustrates interactions between actors/participants over time.

Mermaid.js Quick Reference (2025)

Sun, 31 May 2026 00:00:00 +0000

Mermaid.js Quick Reference (2025) #

Last verified: 2025-09-02

Quick start #

Use a fenced block in Markdown.

flowchart TD
  A[Start] --> B{OK?}
  B -->|Yes| C[Ship]
  B -->|No| D[Fix]

Prefer frontmatter (diagram-local config) over directives when possible.

```mermaid
---
config:
  theme: base
  themeVariables:
    primaryColor: "#00ffb3"
    lineColor: "#222"
---
flowchart LR
  A --> B
```

Browser API (v10+):

<script type="module">
  import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
  mermaid.initialize({ startOnLoad: true });
</script>

Tip: For selective rendering, set startOnLoad: false and call await mermaid.run({ querySelector | nodes, suppressErrors }).

Mermaid.js Syntax: The Golden Rules 📜

Sun, 31 May 2026 00:00:00 +0000

Mermaid.js Syntax: The Golden Rules 📜 #

A condensed guide to writing clean, effective, and error-free Mermaid.js diagrams.

✨ Core Principles #

These rules are the foundation for all Mermaid diagrams.

Declare Diagram Type First Always begin with the diagram type keyword (e.g., flowchart TD, sequenceDiagram). This is non-negotiable.
```
%% ✅ Correct
flowchart TD
    A --> B
```
Unique IDs are Essential Every node/participant/entity needs a unique identifier for linking. Simple IDs are best; avoid special characters.

n8n on Debian 12: The Docker Method

Sun, 31 May 2026 00:00:00 +0000

n8n on Debian 12: The Docker Method #

This guide provides a robust method for installing, configuring, and managing n8n on a Debian 12 server using Docker. This setup is isolated, reproducible, and bypasses potential host system issues with Node.js/npm.

1. Prerequisites #

A server running Debian 12.
A user with sudo privileges (this guide uses dev).
A domain or subdomain ready to be pointed to the server’s IP.

2. Docker Installation #

2.1. Set up Docker’s APT Repository #

# Update package index and install prerequisites
sudo apt-get update
sudo apt-get install -y ca-certificates curl

# Add Docker's official GPG key
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/debian/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

# Add the repository to Apt sources
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/debian \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update

2.2. Install Docker Engine and Compose #

sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

2.3. Add User to Docker Group (Post-installation) #

This allows running Docker commands without sudo. You will need to log out and log back in for this change to take effect.

Obsidian Plugin Development Cheat Sheet

Sun, 31 May 2026 00:00:00 +0000

Obsidian Plugin Development Cheat Sheet #

A comprehensive guide to developing plugins for Obsidian, from setup to release.

🚀 Getting Started #

Prerequisites #

Git: https://git-scm.com/
Node.js: https://nodejs.org/
Code Editor: VS Code is recommended.

Development Vault #

ALWAYS use a separate, dedicated vault for plugin development to avoid data loss in your main vault.
Create a new, empty vault for development purposes.

Sample Plugin Setup #

Clone the sample plugin into your development vault’s .obsidian/plugins directory:

Popular Programming Libraries & Frameworks

Sun, 31 May 2026 00:00:00 +0000

Popular Programming Libraries & Frameworks #

A comprehensive guide to the most popular and influential programming libraries and frameworks in 2024. This cheat sheet is categorized by domain to help you find the right tools for your projects, from web development to data science.

🌐 Web Development - Frontend #

These libraries and frameworks are the building blocks of modern, dynamic user interfaces on the web.

1. React #

📝 Description: A JavaScript library developed by Facebook for building user interfaces, especially for single-page applications. It allows developers to create reusable UI components.
✨ Key Features: Virtual DOM for high performance, component-based architecture, vast ecosystem with tools like Redux for state management and React Router for navigation.
🚀 Why Use It?: Versatile, widely adopted, and backed by a massive community. Powers major apps like Facebook and Instagram.

2. Next.js #

📝 Description: A powerful React framework that enables server-side rendering (SSR), static site generation (SSG), and other advanced features out of the box.
✨ Key Features: Optimized for performance and SEO, automatic code splitting, API routes for full-stack development.
🚀 Why Use It?: The go-to framework for building production-ready React applications, used by companies like Netflix and TikTok.

3. Vue.js #

📝 Description: A progressive JavaScript framework known for its simplicity, gentle learning curve, and excellent documentation.
✨ Key Features: Reactive two-way data binding, component-based, can be adopted incrementally for either small features or full-scale applications.
🚀 Why Use It?: Perfect for small to medium-sized projects and for developers who value simplicity and speed.

4. Svelte #

📝 Description: An innovative framework that compiles your code to tiny, framework-less vanilla JavaScript at build time, resulting in highly performant applications.
✨ Key Features: No virtual DOM, minimal bundle sizes, truly reactive with less boilerplate code.
🚀 Why Use It?: For projects where performance and speed are paramount. It offers a refreshing and simple developer experience.

5. Angular #

📝 Description: A full-fledged, TypeScript-based framework by Google for building robust and scalable single-page applications (SPAs).
✨ Key Features: Two-way data binding, dependency injection, comprehensive built-in tools for routing and state management.
🚀 Why Use It?: Ideal for large, enterprise-level applications that require long-term maintainability and a structured architecture.

⚙️ Web Development - Backend #

These frameworks provide the server-side logic, database interactions, and APIs for web applications.

Public Domain Hits

Sun, 31 May 2026 00:00:00 +0000

Public-domain hits (classical + popular) — 2025 guide

TL;DR ⚖️🎼🎤

Scope: 🇺🇸 US vs 🇪🇺 EU; musical works (compositions) vs sound recordings (masters).
2025 US: Works published in 1929 are PD. Pre‑1972 sound recordings fixed in 1924 are PD (MMA schedule adds one year each Jan 1).
EU: Musical works generally PD 70y post mortem auctoris (life+70). Sound recordings: typically 70y from publication.
Always split rights: use PD composition + PD recording, or make your own recording of a PD composition.

Legal ground truth (practical) 🧩

Python Project X-Ray — Low‑Token Model Pack

Sun, 31 May 2026 00:00:00 +0000

Python Project X-Ray — Low‑Token Model Pack #

A practical, repeatable method to condense any Python codebase into a compact “model pack” that preserves the project’s structure, APIs, interactions, and intent with minimal tokens. Optimized for rapid onboarding of agents/developers and efficient LLM reasoning.

What You Get (Outputs) #

overview.md — high-signal, low-token project narrative and entry points
api.md — public surface: packages/modules/classes/functions with signatures
tree.txt — pruned file tree (noise filtered), sizes, highlights
graph.json — import graph + class inheritance + cross-module usage edges
stats.json — LOC, counts, ranks, hotspots
pack.json — metadata, budgets, and routing hints for LLMs

All outputs are deterministic, source-of-truth derived (AST + file system), and safe to share (secrets filtered by default ignores).

uv: The Blazing-Fast Python Packager

Sun, 31 May 2026 00:00:00 +0000

uv: The Blazing-Fast Python Packager #

uv is an extremely fast Python package installer and resolver, written in Rust. It’s designed to be a drop-in replacement for pip, pip-tools, virtualenv, and more, offering significant performance improvements.

🚀 Core Concepts #

Unified Tool: Aims to replace a fragmented toolchain with a single, cohesive binary.
Speed: 10-100x faster than pip and pip-tools due to its Rust architecture and intelligent caching.
Two Modes:
1. Project Mode: Manages dependencies through pyproject.toml (like Poetry or PDM) using commands like uv add, uv remove, and uv lock.
2. pip-like Mode: Acts as a direct, faster replacement for pip commands (uv pip install, uv pip sync, etc.).
Global Cache: Shares dependencies across projects to save disk space.

📦 Installation #

Install uv with the official script:

Workspace Quick-Start Cheat Sheet 🚀

Sun, 31 May 2026 00:00:00 +0000

Workspace Quick-Start Cheat Sheet 🚀 #

Welcome to the /home/dev server container! This cheatsheet is a high-level, idiot-proof, and ultra-condensed reference map for all active projects, services, port allocations, and dev workflows.

🔌 1. Global Port Allocation Map #

Port	Service / Application	Tech Stack	Project Directory
`7860`	AudioFlux Main App (MIR Modular)	Python, Gradio	`/home/dev/audio/audioflux/`
`7861`	AudioFlux Unified Dashboard	Python, Gradio	`/home/dev/audio/audioflux/`
`7863`	AudioFlux MIR Playground	Python, Gradio	`/home/dev/audio/audioflux/`
`55211`	GOMA (Hugo Backend Site)	Hugo SSG	`/home/dev/hugdown/goma/`
`55212`	GOMA LiveReload Server	Node/Hugo	`/home/dev/hugdown/`
`55220`	GIMA (Vite React Client)	React, Vite	`/home/dev/hugdown/gima/`
`55577`	Langflow Workflow Engine	Python, Poetry	`/home/dev/py/flow/`
`55644`	MixBox NiceGUI Review UI	Python, UV	`/home/dev/audio/mixbox/`
`55441`	Groq Showcase (Full Main UI)	Python, Gradio	`/home/dev/py/groqgradio/`
`55443`	Groq Showcase (Minimal Chat UI)	Python, Gradio	`/home/dev/py/groqgradio/`
`55444`	Groq Showcase (Streamlined Chat)	Python, Gradio	`/home/dev/py/groqgradio/`
`55446`	Groq Showcase (Langflow Proxy)	Python, Gradio	`/home/dev/py/groqgradio/`
`55442`	Jamjams OpenAI Chat Lab	Python, Gradio	`/home/dev/py/gradiomulti/`

📂 2. Absolute Path Directory Map #

/home/dev/audio/mixbox/ 🎛️ — DJ automation & beatgrid editor (FastAPI, NiceGUI, React/OpenDAW).
/home/dev/audio/audioflux/ 📊 — MIR signal analyzer Gradio UI (Pure NumPy/SciPy math, no librosa).
/home/dev/audio/broadcast/ 📻 — Radio streaming orchestration (Icecast & Liquidsoap configs).
/home/dev/audio/nicegui/ 🖥️ — Frontend demo elements & component modifications.
/home/dev/hugdown/ ⚡ — Hybrid static-client site (GIMA React hydration on GOMA Hugo static views).
/home/dev/py/flow/ 🤖 — Visual pipeline node connector & chatbot design environment (Langflow).
/home/dev/py/groqgradio/ ⚡ — Systemd-deployed Gradio UIs hooked up to Groq APIs.
/home/dev/py/gradiomulti/ 🧪 — Multi-service OpenAI Gradio playground via OpenRouter.
/home/dev/py/mugen/ 🎬 — Music Video Creator CLI (Rhythm beats matching video edit).
/home/dev/py/mugen-webui/ 🎞️ — MUGEN editor web control center interface.
/home/dev/active/ 🕹️ — Project sandbox containing ai-town, storymatrix, and express lobbies (fun, funday).

💻 3. Command Central by Project #

🎛️ MixBox (`/home/dev/audio/mixbox/`) #

# Sync package deps via uv
uv sync

# Auto-format and lint code
uv run ruff check . --fix

# Run unit tests (skip slow mix generations)
uv run pytest -m "not rotation"

# Run Quality Gate regression tests (Micro or Afro baseline)
uv run python scripts/rotation_quality_gate.py micro
uv run python scripts/rotation_quality_gate.py afro

# Launch editor UI (Port 55644)
uv run python -m mixbox.gui

📊 AudioFlux Showcase (`/home/dev/audio/audioflux/`) #

# Activate Venv & start all 3 Gradio apps in the background
source .venv/bin/activate
python app/main.py &
python app/unified_main.py &
python mir_playground_standalone.py &

# Kill Gradio apps
pkill -f "main.py\|unified_main.py\|mir_playground_standalone.py"

# Run comprehensive signal engine checks
python -c "exec(open('test_comprehensive.py').read())"

⚡ Hugdown / GIGO (`/home/dev/hugdown/`) #

# Start GOMA (Hugo) and GIMA (React) concurrently
./gigo-start.sh

# Terminate dev environments
./gigo-stop.sh

# Build React client, copy bundles, and generate static Hugo site
./build-all.sh

# Execute integration tests
node test-e2e.js

🤖 Langflow (`/home/dev/py/flow/`) #

# Start visual builder backend (Port 55577)
poetry run langflow run --host 0.0.0.0 --port 55577

⚡ Groq Gradio Services (`/home/dev/py/groqgradio/`) #

# Manage Gradio services via systemd
systemctl --user start groq-minimal.service
systemctl --user start groq-streamlined.service
systemctl --user start groq-main.service
systemctl --user start groq-langflow.service

# Stream service logs
journalctl --user -u groq-minimal -f

🧪 Jamjams Chat Lab (`/home/dev/py/gradiomulti/`) #

# Launch OpenAI OpenRouter Gradio interface (Port 55442)
python app.py

🎞️ MUGEN WebUI (`/home/dev/py/mugen-webui/`) #

# Launch rhythm video generator control UI
python webui.py

🕹️ Active Sandbox #

ai-town: cd /home/dev/active/ai-town && npm run dev
funday: cd /home/dev/active/funday && ./start-funday.sh

🛠️ 4. Essential Coding Conventions #

🐍 Python #

Audio Fallbacks: Use load_audio from audio_core. It targets librosa first and gracefully falls back to pydub-ng.
Audioflux Constraints: Direct imports of librosa or audioflux in /home/dev/audio/audioflux/ are strictly FORBIDDEN. Use local signal math inside app/utils/audio_utils.py.
Pydantic: Declare runtime parameters inside Pydantic structures (packages/dj-engine/src/mixbox/config/models.py).

📦 Node / Vite / Static Site #

CDN Hydration: In Hugdown static views, import React and ReactDOM from https://esm.sh/ inside the HTML layout to avoid dependency bloating.
JWT Credentials: Secure custom endpoints via JWT_SECRET_KEY on HS256 algorithm.

🔬 5. Testing & Verification #

Pytest Suite: Execute unit tests using pytest markers (slow, integration, rotation, perf, viz).
Telemetry Verification: Tracing logs use @langfuse/otel (with a visibility poll timeout of 4000 ms). Never extract get API methods without binding context (traceApi.get(traceId)) to avoid losing this reference context.

🎛️ Pedalboard Cheat Sheet

Sun, 31 May 2026 00:00:00 +0000

🎛️ Pedalboard Cheat Sheet #

Spotify’s Python library for studio-quality audio effects processing

🎯 What is Pedalboard? #

Pedalboard is a Python library built by Spotify’s Audio Intelligence Lab that enables using studio-quality audio effects from within Python and TensorFlow. It’s designed for real-time audio processing, data augmentation for ML models, and creative audio manipulation.

✨ Key Features #

🚀 Performance

Releases Python’s GIL for multi-core processing
300x faster than pySoX for single transforms
2-5x faster than SoxBindings
4x faster file reading than librosa.load

🎵 Audio I/O

🎛️ Python Pedalboard Genius Showcase Demo System

Sun, 31 May 2026 00:00:00 +0000

🎛️ Python Pedalboard Genius Showcase Demo System #

Interactive Educational Platform for Real-Time Audio Effects Processing

🎯 Vision & Mission #

The Python Pedalboard Genius Showcase Demo System is a comprehensive, interactive educational platform designed to introduce beginners and professionals to the power of Spotify’s Pedalboard library through hands-on, real-time audio processing experiences. This system transforms complex audio engineering concepts into accessible, visual, and immediately audible learning modules.

🏗️ CORE ARCHITECTURE & DESIGN PHILOSOPHY CHEAT SHEET

Sun, 31 May 2026 00:00:00 +0000

🏗️ CORE ARCHITECTURE & DESIGN PHILOSOPHY CHEAT SHEET #

Ultra-Condensed Enlightenment Guide - Red 3.5+ Compliant

🧩 MODULAR COG SYSTEM MASTERY (Red 3.5+ Architecture) #

Core Cog Architecture #

# Red 3.5+ Compliant Cog Structure
from redbot.core import commands, Config
import asyncio
import logging

log = logging.getLogger("red.mycog")

# REQUIRED: GDPR Compliance Statement
__red_end_user_data_statement__ = (
    "This cog stores user IDs and guild IDs for configuration purposes. "
    "No personal data is stored."
)

class MyCog(commands.Cog):
    """Modern Red 3.5+ cog implementation"""
    
    def __init__(self, bot):
        self.bot = bot
        self.config = Config.get_conf(
            self, 
            identifier=1234567890,
            force_registration=True  # RED 3.5+ BEST PRACTICE
        )
        self.background_tasks = []
        
        # Register defaults with structured data
        self.config.register_guild(
            enabled=True,
            settings={"feature": False}
        )
    
    async def cog_load(self):
        """Called after __init__ when cog is loaded"""
        log.info("Cog loading...")
        await self.start_background_tasks()
    
    async def cog_unload(self):
        """Called before cog removal - CRITICAL for cleanup"""
        log.info("Cog unloading...")
        for task in self.background_tasks:
            if not task.done():
                task.cancel()
        if self.background_tasks:
            await asyncio.gather(*self.background_tasks, return_exceptions=True)
    
    async def red_delete_data_for_user(self, kwargs):
        """REQUIRED: GDPR compliance data deletion"""
        user_id = kwargs.get("user_id")
        if user_id:
            await self.config.user_from_id(user_id).clear()

# REQUIRED: Async setup function (Red 3.5+)
async def setup(bot):
    """Called by Red when loading the cog - MUST BE ASYNC"""
    cog = MyCog(bot)
    await bot.add_cog(cog)  # add_cog is async in Red 3.5+

Cog Lifecycle Flow (Red 3.5+) #

1. Import Phase → 2. Class Definition → 3. __init__() → 4. cog_load() → 
5. Runtime → 6. cog_unload() → 7. Cleanup → 8. Memory Release

🎯 Registration: Async setup() function with await bot.add_cog()
🔧 Initialization: __init__ for basic setup, cog_load() for async operations
📦 Discovery: Auto-scan via redbot/cogs/ or manual loading
🔄 Hot Reload: Zero-downtime reloading with state preservation
🛠️ Dependencies: Dependency injection via bot instance access
📋 State Isolation: Independent memory space per cog instance
🎪 Event Distribution: Automatic event routing to cog listeners
🧬 Inheritance: Multiple inheritance from commands.Cog base class
🔒 GDPR Compliance: Mandatory data statement and deletion methods

🏛️ BACKEND-FIRST ARCHITECTURE (Separation of Concerns) #

Architectural Layers Visualization #

┌─────────────────────────────────────────────────────────────┐
│                    DISCORD API LAYER                        │
├─────────────────────────────────────────────────────────────┤
│                  CONTEXT ABSTRACTION                        │
│  • Rich Context Objects    • Error Boundaries               │
│  • Permission Validation   • Event Processing               │
├─────────────────────────────────────────────────────────────┤
│                     COG LAYER                               │
│  • Business Logic         • Command Handlers                │
│  • Event Listeners        • Background Tasks                │
├─────────────────────────────────────────────────────────────┤
│                   CONFIG LAYER                              │
│  • Data Persistence       • Scope Management                │
│  • Validation             • Migration                       │
├─────────────────────────────────────────────────────────────┤
│                   DRIVER LAYER                              │
│  • JSON Driver (Default)  • PostgreSQL Driver (Enterprise) │
│  • Storage Abstraction    • Transaction Management          │
└─────────────────────────────────────────────────────────────┘

Implementation Patterns #

# Context Abstraction Pattern
class RichContext:
    """Enhanced context with Red-specific utilities"""
    
    async def tick(self, success=True):
        """Visual confirmation with emoji reactions"""
        emoji = "✅" if success else "❌"
        try:
            await self.message.add_reaction(emoji)
        except discord.HTTPException:
            await self.send(emoji)
    
    async def maybe_send_embed(self, embed):
        """Intelligent embed sending with fallback"""
        if self.channel.permissions_for(self.me).embed_links:
            await self.send(embed=embed)
        else:
            await self.send(embed.description or "No content")

# Error Boundary Implementation
async def cog_command_error(self, ctx, error):
    """Cog-level error handling boundary"""
    if isinstance(error, commands.UserInputError):
        await ctx.send_help(ctx.command)
    elif isinstance(error, commands.CheckFailure):
        await ctx.send("Permission denied")
    else:
        log.exception(f"Unexpected error in {ctx.command}: {error}")

🎯 Separation: Complete isolation of Discord API from business logic
🔧 Abstraction: Rich context objects hide complexity from cogs
📊 Error Boundaries: Layered error handling with graceful degradation
🛡️ Validation: Multi-layer input validation and sanitization
🔄 Async Flow: Full async/await throughout the stack
📡 Event Router: Centralized event distribution to interested cogs
🎨 Presentation: Formatting utilities separate from data logic
🔧 Middleware: Check system as interceptor middleware
📊 Unidirectional: Clean data flow from Discord → Cog → Config
🎯 Testability: Mockable interfaces for comprehensive testing

🏠 INSTANCE MANAGEMENT SYSTEM (Multi-Tenancy) #

Instance Architecture #

# Instance Structure
/home/user/.local/share/Red-DiscordBot/
├── instance1/                    # First bot instance
│   ├── config.json              # Instance configuration
│   ├── cogs/                    # Instance-specific cogs
│   ├── data/                    # Isolated data storage
│   └── logs/                    # Instance logs
├── instance2/                    # Second bot instance  
│   ├── config.json              # Separate configuration
│   ├── cogs/                    # Independent cog storage
│   ├── data/                    # Isolated data
│   └── logs/                    # Separate logs
└── global_cogs/                  # Shared cog repository
    ├── economy/                 # Shared cog code
    ├── moderation/              # Reusable across instances
    └── music/                   # Common functionality

Instance Management Commands #

# Instance Lifecycle Management
redbot-setup                      # Interactive instance creation
redbot-setup --no-prompt         # Automated instance setup
redbot <instance_name>            # Run specific instance
redbot <instance_name> --edit     # Edit instance configuration

# Multi-Instance Operations
redbot-launcher                   # GUI launcher for multiple instances
redbot --list                     # List all instances
redbot --delete <instance>        # Remove instance safely

🎪 Isolation: Complete data and config separation per instance
🗂️ Organization: Structured directory hierarchy for clarity
🔧 Management: CLI tools for instance lifecycle operations
🎯 Flexibility: Different bot tokens, settings per instance
📊 Scaling: Horizontal scaling through instance multiplication
🔄 Migration: Tools for moving data between instances
🛡️ Security: Cross-instance data isolation for safety
📦 Deployment: Docker-ready containerized instances
🎮 Process: Independent process management per instance
🔧 Resource: Shared code base, isolated runtime state

📊 CONFIG ABSTRACTION MASTERY (Data Persistence) #

Scope Hierarchy Visualization #

GLOBAL (0)     ┌─────────────────────────┐
   ↓           │    Bot-wide settings     │
GUILD (1)      ├─────────────────────────┤
   ↓           │   Per-server settings    │
CHANNEL (2)    ├─────────────────────────┤
   ↓           │  Per-channel settings    │ 
ROLE (3)       ├─────────────────────────┤
   ↓           │   Per-role settings      │
USER (4)       ├─────────────────────────┤
   ↓           │ Per-user global settings │
MEMBER (5)     ├─────────────────────────┤
   ↓           │ Per-member guild settings│
CUSTOM (6)     └─────────────────────────┘
               │   Custom identifiers     │

Advanced Config Patterns #

# Modern Config Setup (Red 3.5+)
class AdvancedCog(commands.Cog):
    def __init__(self, bot):
        self.bot = bot
        self.config = Config.get_conf(
            self,
            identifier=1234567890,
            force_registration=True  # PREVENTS SILENT FAILURES
        )
        
        # Structured Default Registration
        default_global = {
            "version": "1.0.0",
            "debug": False,
            "api_keys": {}
        }
        
        default_guild = {
            "enabled": True,
            "prefix": "!",
            "modules": {
                "economy": {"enabled": False, "currency": "credits"},
                "moderation": {"enabled": True, "auto_ban": False}
            },
            "channels": {"log": None, "admin": None},
            "roles": {"moderator": [], "admin": []},
            "permissions": {"custom_commands": []}
        }
        
        # Force registration prevents typos and ensures defaults
        self.config.register_global(default_global)
        self.config.register_guild(default_guild)
        
        # Custom scope for complex data
        self.config.custom("ECONOMY_ACCOUNTS").register(
            balance=0,
            transactions=[],
            daily_last=None
        )
    
    # Safe nested data modification
    async def update_user_balance(self, user_id, amount):
        """Thread-safe balance update with context manager"""
        async with self.config.custom("ECONOMY_ACCOUNTS", user_id).all() as data:
            data["balance"] += amount
            data["transactions"].append({
                "amount": amount,
                "timestamp": datetime.utcnow().isoformat(),
                "type": "admin_adjustment"
            })

Driver Architecture Comparison #

JSON Driver (Default)          PostgreSQL Driver (Enterprise)
┌──────────────────────┐      ┌──────────────────────────────┐
│ • File-based storage │      │ • Database storage           │
│ • Human readable     │      │ • ACID compliance            │
│ • Easy debugging     │      │ • Enterprise scale           │
│ • Simple backup      │      │ • Clustering support         │
│ • < 10MB datasets    │      │ • Professional monitoring    │
│ • Development focus  │      │ • Production focus           │
└──────────────────────┘      └──────────────────────────────┘

🎯 Hierarchy: 7-level scope system from global to custom
🔧 Value Types: Value (primitives) vs Group (containers)
📦 Force Registration: Prevents typos and ensures default values
🔒 Thread Safety: Per-value asyncio locks for concurrent access
🎨 Context Managers: Safe mutable data modification patterns
🗄️ Driver Agnostic: Pluggable storage backends (JSON/PostgreSQL)
🔄 Caching: Intelligent weak reference caching system
📊 Deep Nesting: Unlimited nested data structure support
🧹 Cleanup: Comprehensive data cleanup and maintenance APIs
🎯 Migration: Schema versioning and automated migration tools

🛡️ PERMISSION FRAMEWORK ARCHITECTURE #

Permission Hierarchy Flow #

# Permission Privilege Levels (Ascending Order)
PRIVILEGE_LEVELS = {
    "NONE": 0,           # No special privileges
    "MOD": 1,            # Moderator level
    "ADMIN": 2,          # Administrator level  
    "GUILD_OWNER": 3,    # Guild owner privileges
    "BOT_OWNER": 4       # Bot owner (highest)
}

# Permission Model Implementation
class PermissionManager:
    def __init__(self, bot):
        self.bot = bot
        self.global_perms = GlobalPermissionModel(bot)
        self.guild_perms = GuildPermissionModel(bot)
        self.channel_perms = ChannelPermissionModel(bot)
    
    async def check_permissions(self, ctx, required_level):
        """Hierarchical permission checking"""
        user_level = await self.get_user_privilege_level(ctx)
        
        # Check global whitelist/blacklist first
        if await self.global_perms.is_user_blacklisted(ctx.author):
            return False
        if await self.global_perms.is_user_whitelisted(ctx.author):
            return True
            
        # Check guild-specific permissions
        if ctx.guild:
            guild_level = await self.guild_perms.get_user_level(ctx)
            if guild_level >= required_level:
                return True
                
        # Fallback to user privilege level
        return user_level >= required_level

# Permission Decorators
@commands.check_any(
    checks.is_owner(),
    checks.admin_or_permissions(manage_guild=True),
    checks.has_role("Administrator")
)
async def admin_command(self, ctx):
    """Multi-layer permission checking"""
    await ctx.send("Admin command executed")

Permission Inheritance Tree #

Bot Owner (Level 4)
   ↓ (inherits all)
Guild Owner (Level 3)
   ↓ (inherits below)
Administrator (Level 2)
   ↓ (inherits below)  
Moderator (Level 1)
   ↓ (inherits below)
Regular User (Level 0)

🎯 Hierarchy: 5-level privilege system with inheritance
🔧 Models: Specialized permission models per scope
📊 Predicate System: Flexible predicate-based checking
🎨 Decorators: Rich decorator system for command protection
🔄 Runtime Changes: Dynamic permission modification
🛠️ Integration: Deep Discord role/permission integration
📋 Filtering: User and guild whitelist/blacklist systems
🎯 Validation: Multi-layer validation with safety checks
🔒 Audit Trail: Permission change logging and history
📊 Inheritance: Smart permission inheritance from higher levels

🎯 COMMAND FRAMEWORK STRUCTURE (Red 3.5+) #

Command Class Hierarchy #

# Command Type Evolution
┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   Command       │    │      Group       │    │  HybridCommand  │
│   (Basic)       │    │   (Container)    │    │ (Slash + Text)  │
├─────────────────┤    ├──────────────────┤    ├─────────────────┤
│ • Single action │    │ • Sub-commands   │    │ • Modern syntax │
│ • Simple args   │    │ • Organization   │    │ • Dual support  │
│ • Text only     │    │ • Hierarchical   │    │ • Future-proof  │
└─────────────────┘    └──────────────────┘    └─────────────────┘

# Advanced Command Implementation
class ModernCog(commands.Cog):
    @commands.hybrid_command()  # Red 3.5+ hybrid commands
    @app_commands.describe(user="User to check")
    async def profile(self, ctx, user: discord.Member = None):
        """Get user profile (works as slash and text command)"""
        user = user or ctx.author
        
        # Rich context usage
        embed = discord.Embed(
            title=f"{user.display_name}'s Profile",
            color=await ctx.embed_color()  # Theme-aware color
        )
        
        # Visual confirmation
        await ctx.tick()  # ✅ reaction
        await ctx.send(embed=embed)
    
    @commands.group(invoke_without_command=True)
    async def config(self, ctx):
        """Configuration command group"""
        if ctx.invoked_subcommand is None:
            await ctx.send_help(ctx.command)
    
    @config.command()
    @commands.admin_or_permissions(manage_guild=True)
    @commands.cooldown(1, 30, commands.BucketType.guild)
    async def toggle(self, ctx, *, feature: str):
        """Toggle a configuration feature"""
        async with self.config.guild(ctx.guild).features() as features:
            features[feature] = not features.get(feature, False)
        
        status = "enabled" if features[feature] else "disabled"
        await ctx.send(f"Feature `{feature}` {status}")

Converter System Architecture #

# Built-in Converter Ecosystem
BUILT_IN_CONVERTERS = {
    # Discord Objects
    "discord.Member": "User in current guild",
    "discord.User": "Any Discord user", 
    "discord.TextChannel": "Text channel",
    "discord.Role": "Guild role",
    "discord.Emoji": "Custom emoji",
    
    # Utility Converters  
    "commands.Greedy": "Multiple arguments",
    "typing.Union": "Multiple type options",
    "typing.Optional": "Optional argument",
    
    # Red-specific
    "redbot.core.commands.Context": "Enhanced context",
    "redbot.core.utils.chat_formatting.TimedeltaConverter": "Time spans"
}

# Custom Converter Example
class ConfigKeyConverter(commands.Converter):
    """Converter for configuration keys with validation"""
    
    async def convert(self, ctx, argument):
        valid_keys = await ctx.cog.config.guild(ctx.guild).all()
        if argument not in valid_keys:
            raise commands.BadArgument(
                f"Invalid config key. Valid keys: {', '.join(valid_keys)}"
            )
        return argument

🎮 Command Types: Command, Group, HybridCommand for different patterns
🔧 Converters: 20+ built-in converters plus custom converter support
📊 Context: Enhanced context with utilities like tick(), embed_color()
🎨 Help System: Sophisticated help generation with customizable formatting
🔄 Error Handling: Comprehensive error class hierarchy with graceful handling
🛡️ Validation: Automatic argument validation and type checking
🎯 Parsing: Advanced argument parsing with flags and keyword support
📋 Cooldowns: Sophisticated rate limiting with multiple bucket types
🔧 Hooks: Before/after invoke hooks for command processing middleware
🎪 Dynamic: Runtime command addition/removal with hot-swapping

🚀 AUTOSHARDED BOT FOUNDATION #

Shard Architecture Flow #

# AutoShardedBot Inheritance Chain
discord.AutoShardedBot → commands.AutoShardedBot → Red (Bot Class)

class RedBot(commands.AutoShardedBot):
    """Red's enhanced autosharded bot implementation"""
    
    def __init__(self, *args, kwargs):
        super().__init__(*args, kwargs)
        self.uptime = datetime.utcnow()
        self.counter = Counter()
        self._config = None
        self._disabled_commands = []
        
    async def on_shard_connect(self, shard_id):
        """Called when a shard connects"""
        log.info(f"Shard {shard_id} connected")
        
    async def on_shard_disconnect(self, shard_id):
        """Called when a shard disconnects"""
        log.warning(f"Shard {shard_id} disconnected")
        
    async def on_shard_ready(self, shard_id):
        """Called when a shard is ready"""
        log.info(f"Shard {shard_id} ready")
        await self.update_shard_stats(shard_id)

# Shard Health Monitoring
async def monitor_shard_health(bot):
    """Monitor and report shard health"""
    while True:
        unhealthy_shards = []
        for shard_id, shard in bot.shards.items():
            if shard.latency > 1.0:  # High latency
                unhealthy_shards.append(shard_id)
            
        if unhealthy_shards:
            log.warning(f"Unhealthy shards detected: {unhealthy_shards}")
            
        await asyncio.sleep(60)  # Check every minute

Shard Distribution Logic #

Guild Distribution Across Shards:
Shard 0: Guilds 0, 4, 8, 12...     (guild_id % shard_count == 0)
Shard 1: Guilds 1, 5, 9, 13...     (guild_id % shard_count == 1) 
Shard 2: Guilds 2, 6, 10, 14...    (guild_id % shard_count == 2)
Shard 3: Guilds 3, 7, 11, 15...    (guild_id % shard_count == 3)

🎯 Base: Inherits from discord.py’s AutoShardedBot for scalability
🔧 Management: Automatic shard management for large bot deployments
📊 Distribution: Automatic load balancing across multiple shards
🎨 Event Routing: Events distributed to all shards automatically
🔄 Fault Tolerance: Individual shard failure isolation and recovery
🛡️ Scaling: Automatic scaling based on guild count thresholds
📦 Gateway: Intelligent gateway connection management per shard
🎯 Latency: Per-shard latency tracking and optimization
🔧 Reconnection: Robust reconnection handling with exponential backoff
📊 Monitoring: Built-in shard health monitoring and alerting

🔒 CONCURRENCY & LOCKING (Thread Safety) #

Lock Granularity System #

# Lock Hierarchy (Fine to Coarse)
Per-Value Lock → Per-Group Lock → Per-Scope Lock → Global Lock

# Practical Lock Implementation
class ThreadSafeConfigManager:
    def __init__(self, config):
        self.config = config
        self._locks = {}
        
    async def safe_increment(self, user_id):
        """Thread-safe counter increment"""
        lock_key = f"user_{user_id}_counter"
        
        # Get or create lock for this specific value
        if lock_key not in self._locks:
            self._locks[lock_key] = asyncio.Lock()
            
        async with self._locks[lock_key]:
            current = await self.config.user_from_id(user_id).counter()
            new_value = current + 1
            await self.config.user_from_id(user_id).counter.set(new_value)
            return new_value
    
    async def bulk_update_guild_data(self, guild_id, updates):
        """Thread-safe bulk data update"""
        async with self.config.guild_from_id(guild_id).all() as guild_data:
            for key, value in updates.items():
                guild_data[key] = value
            # Automatic commit on context exit
            
# Deadlock Prevention Pattern
async def safe_multi_lock_operation(config, user_id1, user_id2):
    """Prevent deadlocks with ordered locking"""
    # Always acquire locks in consistent order (by ID)
    ids = sorted([user_id1, user_id2])
    
    async with config.user_from_id(ids[0]).balance.get_lock():
        async with config.user_from_id(ids[1]).balance.get_lock():
            # Perform operations safely
            balance1 = await config.user_from_id(ids[0]).balance()
            balance2 = await config.user_from_id(ids[1]).balance()
            
            # Transfer between users safely
            await config.user_from_id(ids[0]).balance.set(balance1 - 100)
            await config.user_from_id(ids[1]).balance.set(balance2 + 100)

Concurrency Best Practices #

# Lock Timeout Handling
async def safe_config_operation(config, timeout=5.0):
    """Config operation with timeout protection"""
    try:
        async with asyncio.wait_for(
            config.guild(guild).settings.get_lock(),
            timeout=timeout
        ):
            # Perform operation
            settings = await config.guild(guild).settings()
            settings["last_updated"] = datetime.utcnow()
            await config.guild(guild).settings.set(settings)
            
    except asyncio.TimeoutError:
        log.warning("Config operation timed out")
        return False
    return True

# Resource Cleanup Pattern
class ResourceManagedCog(commands.Cog):
    def __init__(self, bot):
        self.bot = bot
        self.active_locks = WeakSet()
        
    async def cog_unload(self):
        """Ensure all locks are released on unload"""
        for lock in list(self.active_locks):
            if lock.locked():
                lock.release()
        self.active_locks.clear()

🎯 Granularity: Per-value locks minimize contention
🔧 Context Managers: Async context managers for automatic cleanup
📊 Deadlock Prevention: Ordered locking algorithms prevent deadlocks
🎨 Performance: Lock-free operations where thread safety isn’t needed
🔄 Timeout Handling: Configurable lock timeouts prevent hanging
🛡️ Error Recovery: Automatic lock cleanup on exceptions
📦 Resource Management: Weak references for automatic lock cleanup
🎯 Debugging: Lock state monitoring and debugging capabilities
🔧 Optimization: Lock contention minimization strategies
📊 Metrics: Performance monitoring for lock optimization

📦 SINGLETON PATTERN IMPLEMENTATION (ConfigMeta) #

Metaclass Architecture #

# ConfigMeta Implementation Details
class ConfigMeta(type):
    """Metaclass ensuring singleton config per cog/identifier"""
    
    _instances = {}  # Global registry of config instances
    
    def __call__(cls, cog_instance, identifier, kwargs):
        # Create unique key for cog instance + identifier
        key = (id(cog_instance), identifier)
        
        if key not in cls._instances:
            # Create new instance if not exists
            instance = super().__call__(cog_instance, identifier, kwargs)
            cls._instances[key] = instance
            log.debug(f"Created new config instance: {key}")
        else:
            log.debug(f"Reusing existing config instance: {key}")
            
        return cls._instances[key]
    
    @classmethod
    def cleanup_instance(cls, cog_instance, identifier):
        """Clean up config instance when cog unloads"""
        key = (id(cog_instance), identifier)
        if key in cls._instances:
            del cls._instances[key]
            log.debug(f"Cleaned up config instance: {key}")

# Config Class with Singleton Pattern
class Config(metaclass=ConfigMeta):
    """Configuration manager with singleton enforcement"""
    
    def __init__(self, cog_instance, identifier, kwargs):
        self.cog_instance = cog_instance
        self.identifier = identifier
        self._driver = None
        self._defaults = {}
        
    @classmethod
    def get_conf(cls, cog_instance, identifier, kwargs):
        """Primary entry point - enforces singleton pattern"""
        return cls(cog_instance, identifier, kwargs)
        
    def __del__(self):
        """Cleanup on garbage collection"""
        if hasattr(self, 'cog_instance') and hasattr(self, 'identifier'):
            ConfigMeta.cleanup_instance(self.cog_instance, self.identifier)

# Usage Pattern Ensuring Singleton
class MyCog(commands.Cog):
    def __init__(self, bot):
        self.bot = bot
        # This will always return the same instance for this cog
        self.config = Config.get_conf(self, identifier=12345)
        
    async def cog_unload(self):
        """Singleton cleanup on cog unload"""
        ConfigMeta.cleanup_instance(self, 12345)

Instance Tracking System #

# Debug and Monitoring Tools
class ConfigInstanceMonitor:
    @staticmethod
    def get_active_instances():
        """Get all active config instances"""
        return list(ConfigMeta._instances.keys())
    
    @staticmethod
    def get_instance_count():
        """Get total number of active instances"""
        return len(ConfigMeta._instances)
    
    @staticmethod  
    def detect_leaked_instances():
        """Detect potentially leaked config instances"""
        leaked = []
        for (cog_id, identifier), instance in ConfigMeta._instances.items():
            # Check if cog instance still exists
            if not hasattr(instance, 'cog_instance') or instance.cog_instance is None:
                leaked.append((cog_id, identifier))
        return leaked

🎯 Metaclass: ConfigMeta ensures single instance per cog/identifier pair
🔧 Registry: Global instance registry for tracking and cleanup
📊 Memory Safety: Prevents memory leaks from duplicate configs
🎨 Conflict Prevention: Eliminates configuration conflicts and overwrites
🔄 Cleanup: Automatic cleanup on cog unload and garbage collection
🛡️ Thread Safety: Thread-safe singleton implementation with locks
📦 Resource Efficiency: Optimal memory usage through instance reuse
🎯 Debugging: Instance tracking and leak detection capabilities
🔧 Validation: Duplicate prevention with clear error messages
📊 Monitoring: Instance lifecycle monitoring and reporting

⚡ QUICK ARCHITECTURE REFERENCE (Red 3.5+) #

# Complete Modern Cog Template (Production-Ready)
from redbot.core import commands, Config, checks
import asyncio
import logging

log = logging.getLogger("red.mycog")

# REQUIRED: GDPR compliance statement
__red_end_user_data_statement__ = (
    "This cog stores user IDs and guild IDs for configuration purposes. "
    "No personal data is stored."
)

class ProductionCog(commands.Cog):
    """Production-ready cog with all best practices"""
    
    def __init__(self, bot):
        self.bot = bot
        self.config = Config.get_conf(
            self, 
            identifier=1234567890,
            force_registration=True  # RED 3.5+ BEST PRACTICE
        )
        
        # Structured defaults
        self.config.register_global(version="1.0.0", enabled=True)
        self.config.register_guild(
            enabled=True,
            settings={"feature": False},
            channels={"log": None}
        )
        
        self.background_tasks = []
        
    async def cog_load(self):
        """Initialize after cog loading"""
        log.info("ProductionCog loading...")
        await self.start_background_tasks()
        
    async def cog_unload(self):
        """Cleanup before cog removal"""
        log.info("ProductionCog unloading...")
        for task in self.background_tasks:
            if not task.done():
                task.cancel()
        if self.background_tasks:
            await asyncio.gather(*self.background_tasks, return_exceptions=True)
            
    async def red_delete_data_for_user(self, kwargs):
        """REQUIRED: GDPR data deletion"""
        user_id = kwargs.get("user_id")
        if user_id:
            await self.config.user_from_id(user_id).clear()
    
    @commands.hybrid_command()  # Modern hybrid command
    async def hello(self, ctx):
        """Say hello (works as slash and text command)"""
        await ctx.tick()  # Visual confirmation
        await ctx.send("Hello!")

# REQUIRED: Async setup function
async def setup(bot):
    """Load the cog - MUST BE ASYNC in Red 3.5+"""
    cog = ProductionCog(bot)
    await bot.add_cog(cog)  # add_cog is async

# Instance Management Commands
redbot-setup                      # Create new instance
redbot <instance>                 # Run instance
redbot <instance> --edit          # Edit instance config

# Essential CLI Commands  
[p]load cogname                   # Load cog
[p]unload cogname                 # Unload cog
[p]reload cogname                 # Reload cog (hot reload)
[p]cogs                          # List all cogs

# Config Scope Quick Reference
GLOBAL = 0     # await config.setting()
GUILD = 1      # await config.guild(guild).setting()
CHANNEL = 2    # await config.channel(channel).setting()  
ROLE = 3       # await config.role(role).setting()
USER = 4       # await config.user(user).setting()
MEMBER = 5     # await config.member(member).setting()
CUSTOM = 6     # await config.custom("SCOPE", id).setting()

🏗️ Master Red 3.5+ architecture patterns for bulletproof, scalable, and maintainable Discord bots. This foundation enables all advanced features with 100% accuracy and modern best practices!

🖥️ tmux Cheat Sheet

Sun, 31 May 2026 00:00:00 +0000

🖥️ tmux Cheat Sheet #

📋 What is tmux? #

tmux (Terminal Multiplexer) is a powerful command-line tool that allows you to:

Create multiple terminal sessions within a single window
Detach and reattach to sessions (survive SSH disconnections)
Split windows into panes for multitasking
Share sessions between multiple users
Keep processes running in the background

🚀 Installation #

Ubuntu/Debian #

sudo apt update
sudo apt install tmux

CentOS/RHEL/Fedora #

# CentOS/RHEL 7
sudo yum install tmux

# CentOS/RHEL 8+ / Fedora
sudo dnf install tmux

macOS #

brew install tmux

Verify Installation #

tmux -V

🏗️ Core Concepts #

Hierarchy #

Session: Collection of windows (like a workspace)
Window: Collection of panes (like browser tabs)
Pane: Individual terminal instance (split screen)

Prefix Key #

Default prefix: Ctrl-b (press before any tmux command) All shortcuts below assume you press Ctrl-b first

🧩 COG DEVELOPMENT & LIFECYCLE CHEAT SHEET

Sun, 31 May 2026 00:00:00 +0000

🧩 COG DEVELOPMENT & LIFECYCLE CHEAT SHEET #

Ultra-Condensed Enlightenment Guide - CORRECTED VERSION

🏗️ COG ARCHITECTURE FOUNDATION #

🎯 Base Class: All cogs inherit from commands.Cog
🔧 Lifecycle Methods: __init__, cog_load(), cog_unload(), cog_check()
📊 Registration: async setup() function required for bot discovery
🎨 GDPR Compliance: __red_end_user_data_statement__ module-level string
🔄 State Management: Instance variables for cog-specific data storage
🛡️ Error Handling: Built-in error boundaries and exception isolation per cog
📦 Resource Management: Automatic cleanup on unload via cog_unload()
🎯 Event Handling: @commands.Cog.listener() for Discord events
🔧 Dependencies: Inter-cog communication via bot instance
📊 Configuration: Config instance per cog with unique identifier

🔄 COG LIFECYCLE MASTERY #

Complete Lifecycle Flow (Red 3.5+ Pattern) #

# 1. Import Phase
from redbot.core import commands, Config
import asyncio
import logging

log = logging.getLogger("red.mycog.cog_name")

# 2. GDPR Compliance Statement (Required)
__red_end_user_data_statement__ = (
    "This cog stores user IDs and guild IDs for configuration purposes. "
    "No personal data is stored."
)

# 3. Class Definition
class MyCog(commands.Cog):
    """Cog description for help system"""
    
    def __init__(self, bot):
        # 4. Initialization Phase
        self.bot = bot
        self.config = Config.get_conf(
            self, 
            identifier=1234567890,
            force_registration=True  # Recommended best practice
        )
        self.background_tasks = []
        
        # Register default values
        default_guild = {"enabled": True, "channel": None}
        self.config.register_guild(**default_guild)
    
    async def cog_load(self):
        """5. Load Phase - runs after __init__"""
        log.info("Cog loaded successfully")
        # Start background tasks
        task = asyncio.create_task(self.background_loop())
        self.background_tasks.append(task)
        # Initialize external connections
        await self.init_external_apis()
    
    async def cog_unload(self):
        """6. Unload Phase - cleanup before removal"""
        log.info("Cog unloading...")
        # Cancel background tasks
        for task in self.background_tasks:
            if not task.done():
                task.cancel()
        # Wait for task completion
        if self.background_tasks:
            await asyncio.gather(*self.background_tasks, return_exceptions=True)
        # Close external connections
        await self.cleanup_external_apis()
        # Save any pending data
        await self.save_data()
    
    def cog_check(self, ctx):
        """7. Global check - runs before every command"""
        # Check if cog is enabled in guild
        if not ctx.guild:
            return True  # Always allow in DMs
        return self.config.guild(ctx.guild).enabled()
    
    async def red_delete_data_for_user(self, **kwargs):
        """8. GDPR Data Deletion (Required)"""
        user_id = kwargs.get("user_id")
        if user_id:
            await self.config.user_from_id(user_id).clear()

# 9. Setup Function (Required - MUST be async in Red 3.5+)
async def setup(bot):
    """Called by Red when loading the cog"""
    cog = MyCog(bot)
    await bot.add_cog(cog)  # add_cog is async in Red 3.5+
    
# 10. Teardown Function (Optional - MUST be async in Red 3.5+)
async def teardown(bot):
    """Called by Red when unloading the cog"""
    cog = bot.get_cog("MyCog")
    if cog:
        await cog.cleanup_resources()

Lifecycle State Management #

class StatefulCog(commands.Cog):
    def __init__(self, bot):
        self.bot = bot
        self.loaded = False
        self.ready = False
        self.connections = {}
        self.cache = {}
        self.tasks = []
        
    async def cog_load(self):
        """Transition to loaded state"""
        self.loaded = True
        await self.initialize_resources()
        self.ready = True
        
    async def cog_unload(self):
        """Cleanup and state reset"""
        self.ready = False
        # Cancel all tasks
        for task in self.tasks:
            if not task.done():
                task.cancel()
        if self.tasks:
            await asyncio.gather(*self.tasks, return_exceptions=True)
        await self.cleanup_resources()
        self.loaded = False
        
    def is_ready(self):
        """Check if cog is ready for use"""
        return self.loaded and self.ready

📊 COG STRUCTURE PATTERNS #

Standard Cog Template (Red 3.5+ Compliant) #

from redbot.core import commands, Config, checks
from redbot.core.bot import Red
from redbot.core.utils.chat_formatting import box, pagify
import discord
import asyncio
import logging

log = logging.getLogger("red.mycog")

# REQUIRED: GDPR compliance statement
__red_end_user_data_statement__ = (
    "This cog stores user IDs and guild IDs for configuration purposes. "
    "No personal data is stored."
)

class MyCog(commands.Cog):
    """
    Detailed cog description for the help system.
    
    This cog provides functionality for...
    """
    
    def __init__(self, bot: Red):
        self.bot = bot
        self.config = Config.get_conf(
            self, 
            identifier=1234567890,
            force_registration=True  # Best practice
        )
        
        # Configuration defaults
        self.config.register_global(
            enabled=True,
            debug=False
        )
        
        self.config.register_guild(
            enabled=True,
            channel=None,
            roles=[],
            settings={}
        )
        
        self.config.register_user(
            opted_in=False,
            preferences={}
        )
        
        # Cog state
        self.background_tasks = []
        self.connections = {}
        self.cache = {}
        
    async def cog_load(self):
        """Initialize cog after bot is ready"""
        log.info("Loading MyCog...")
        await self.initialize_cache()
        await self.start_background_tasks()
        log.info("MyCog loaded successfully")
        
    async def cog_unload(self):
        """Cleanup before cog removal"""
        log.info("Unloading MyCog...")
        await self.stop_background_tasks()
        await self.cleanup_connections()
        log.info("MyCog unloaded successfully")
        
    def cog_check(self, ctx):
        """Global check for all commands in this cog"""
        # Allow DMs, check guild settings
        if not ctx.guild:
            return True
        return self.config.guild(ctx.guild).enabled()
        
    async def red_delete_data_for_user(self, **kwargs):
        """Required for GDPR compliance"""
        user_id = kwargs.get("user_id")
        if user_id:
            await self.config.user_from_id(user_id).clear()

Advanced Cog with Dependencies #

class AdvancedCog(commands.Cog):
    def __init__(self, bot):
        self.bot = bot
        self.dependencies = ["Economy", "Modlog"]  # Required cogs
        self.optional_deps = ["Audio", "Trivia"]   # Optional cogs
        
    async def cog_load(self):
        """Check dependencies on load"""
        missing_deps = []
        for dep in self.dependencies:
            if not self.bot.get_cog(dep):
                missing_deps.append(dep)
                
        if missing_deps:
            raise RuntimeError(f"Missing required cogs: {missing_deps}")
            
        # Optional dependency integration
        for dep in self.optional_deps:
            cog = self.bot.get_cog(dep)
            if cog:
                await self.integrate_with_cog(cog)

🎯 COMMAND IMPLEMENTATION PATTERNS #

Command Organization Best Practices #

class OrganizedCog(commands.Cog):
    # Basic commands
    @commands.command()
    async def ping(self, ctx):
        """Simple ping command"""
        await ctx.send("Pong!")
    
    # Group commands
    @commands.group(invoke_without_command=True)
    async def config(self, ctx):
        """Configuration commands"""
        if ctx.invoked_subcommand is None:
            await ctx.send_help(ctx.command)
    
    @config.command(name="set")
    @checks.admin_or_permissions(manage_guild=True)
    async def config_set(self, ctx, setting, *, value):
        """Set a configuration value"""
        async with self.config.guild(ctx.guild).settings() as settings:
            settings[setting] = value
        await ctx.tick()
    
    @config.command(name="get")
    async def config_get(self, ctx, setting):
        """Get a configuration value"""
        settings = await self.config.guild(ctx.guild).settings()
        value = settings.get(setting, "Not set")
        await ctx.send(f"{setting}: {value}")
    
    # Event listeners
    @commands.Cog.listener()
    async def on_message(self, message):
        """Handle message events"""
        # Exit early if bot or disabled
        if message.author.bot:
            return
        if message.guild and await self.bot.cog_disabled_in_guild(self, message.guild):
            return
        # Process message
        await self.process_user_message(message)
    
    @commands.Cog.listener()
    async def on_member_join(self, member):
        """Handle member join events"""
        # Check if enabled in guild
        if await self.bot.cog_disabled_in_guild(self, member.guild):
            return
        # Welcome new members
        await self.welcome_member(member)

📦 BACKGROUND TASK MANAGEMENT #

Task Lifecycle Management (Red 3.5+ Pattern) #

class BackgroundCog(commands.Cog):
    def __init__(self, bot):
        self.bot = bot
        self.tasks = []
        
    async def cog_load(self):
        """Start all background tasks"""
        self.tasks.append(asyncio.create_task(self.cleanup_loop()))
        self.tasks.append(asyncio.create_task(self.update_loop()))
        self.tasks.append(asyncio.create_task(self.monitor_loop()))
        
    async def cog_unload(self):
        """Cancel all background tasks"""
        for task in self.tasks:
            if not task.done():
                task.cancel()
        # Wait for cancellation to complete
        if self.tasks:
            await asyncio.gather(*self.tasks, return_exceptions=True)
        self.tasks.clear()
        
    async def cleanup_loop(self):
        """Periodic cleanup task"""
        try:
            while True:
                await self.perform_cleanup()
                await asyncio.sleep(3600)  # Every hour
        except asyncio.CancelledError:
            log.debug("Cleanup task cancelled")
            raise  # Re-raise to ensure proper cancellation
        except Exception as e:
            log.exception(f"Error in cleanup loop: {e}")
            
    async def update_loop(self):
        """Periodic update task"""
        try:
            while True:
                await self.update_data()
                await asyncio.sleep(300)  # Every 5 minutes
        except asyncio.CancelledError:
            log.debug("Update task cancelled")
            raise
        except Exception as e:
            log.exception(f"Error in update loop: {e}")

Task Recovery and Health Monitoring #

async def ensure_task_health(self):
    """Check and restart failed tasks"""
    new_tasks = []
    for i, task in enumerate(self.tasks):
        if task.done() and not task.cancelled():
            # Task completed unexpectedly, restart it
            exception = task.exception()
            if exception:
                log.error(f"Task {i} failed: {exception}")
            
            # Restart based on task type
            if i == 0:  # cleanup task
                new_tasks.append(asyncio.create_task(self.cleanup_loop()))
            elif i == 1:  # update task
                new_tasks.append(asyncio.create_task(self.update_loop()))
        else:
            new_tasks.append(task)
    
    self.tasks = new_tasks

🔧 ERROR HANDLING & VALIDATION #

Comprehensive Error Handling #

class RobustCog(commands.Cog):
    @commands.Cog.listener()
    async def on_command_error(self, ctx, error):
        """Handle errors for this cog's commands"""
        # Only handle errors from this cog's commands
        if not hasattr(ctx.command, "cog") or ctx.command.cog != self:
            return
            
        if isinstance(error, commands.MissingRequiredArgument):
            await ctx.send(f"Missing argument: {error.param}")
            await ctx.send_help(ctx.command)
            
        elif isinstance(error, commands.BadArgument):
            await ctx.send(f"Invalid argument: {error}")
            await ctx.send_help(ctx.command)
            
        elif isinstance(error, commands.CheckFailure):
            await ctx.send("You don't have permission to use this command")
            
        elif isinstance(error, commands.CommandOnCooldown):
            await ctx.send(f"Command on cooldown: {error.retry_after:.1f}s")
            
        else:
            # Log unexpected errors
            log.exception(f"Unexpected error in {ctx.command}: {error}")
            await ctx.send("An unexpected error occurred")
    
    async def validate_configuration(self):
        """Validate cog configuration"""
        try:
            config = await self.config.all()
            # Validate configuration structure
            required_keys = ["enabled", "settings"]
            for key in required_keys:
                if key not in config:
                    log.warning(f"Missing config key: {key}")
                    
        except Exception as e:
            log.error(f"Configuration validation failed: {e}")

🔗 INTER-COG COMMUNICATION #

Safe Cog Communication Patterns #

class CommunicatingCog(commands.Cog):
    def get_economy_cog(self):
        """Safely get Economy cog"""
        return self.bot.get_cog("Economy")
    
    async def add_currency(self, user, amount):
        """Add currency via Economy cog"""
        economy = self.get_economy_cog()
        if economy and hasattr(economy, "deposit_credits"):
            try:
                from redbot.core import bank
                await bank.deposit_credits(user, amount)
                return True
            except Exception as e:
                log.error(f"Failed to add currency: {e}")
        return False
    
    async def check_cog_compatibility(self, cog_name, required_methods):
        """Check if another cog has required methods"""
        cog = self.bot.get_cog(cog_name)
        if not cog:
            return False
            
        for method in required_methods:
            if not hasattr(cog, method):
                return False
        return True
    
    @commands.command()
    async def reward(self, ctx, user: discord.Member, amount: int):
        """Reward user with currency"""
        if await self.add_currency(user, amount):
            await ctx.send(f"Added {amount} credits to {user}")
        else:
            await ctx.send("Economy system not available")

📋 DATA PERSISTENCE PATTERNS #

Configuration Best Practices (Red 3.5+) #

class DataManagedCog(commands.Cog):
    def __init__(self, bot):
        self.bot = bot
        self.config = Config.get_conf(
            self, 
            identifier=1234567890,
            force_registration=True  # Red 3.5+ best practice
        )
        
        # Structured defaults
        default_global = {
            "version": "1.0.0",
            "enabled": True,
            "settings": {
                "debug": False,
                "rate_limit": 100
            }
        }
        
        default_guild = {
            "enabled": True,
            "prefix": "!",
            "channels": {
                "log": None,
                "admin": None
            },
            "roles": {
                "moderator": [],
                "admin": []
            },
            "features": {
                "automod": False,
                "logging": True
            }
        }
        
        self.config.register_global(**default_global)
        self.config.register_guild(**default_guild)
    
    async def migrate_data(self):
        """Handle data migration between versions"""
        version = await self.config.version()
        if version < "1.1.0":
            await self.migrate_to_v1_1_0()
        if version < "1.2.0":
            await self.migrate_to_v1_2_0()
    
    async def backup_data(self):
        """Create data backup"""
        from datetime import datetime
        all_data = await self.config.all()
        backup_data = {
            "timestamp": datetime.utcnow().isoformat(),
            "version": await self.config.version(),
            "data": all_data
        }
        return backup_data

⚡ QUICK COG REFERENCE #

# Minimal Cog Structure (Red 3.5+)
__red_end_user_data_statement__ = "No user data stored."

class MyCog(commands.Cog):
    def __init__(self, bot):
        self.bot = bot
        self.config = Config.get_conf(self, identifier=12345, force_registration=True)
        
    @commands.command()
    async def hello(self, ctx):
        await ctx.send("Hello!")

async def setup(bot):  # MUST be async in Red 3.5+
    await bot.add_cog(MyCog(bot))

# Loading/Unloading Commands
[p]load cog_name          # Load cog
[p]unload cog_name        # Unload cog  
[p]reload cog_name        # Reload cog
[p]cogs                   # List all cogs

# Cog Directory Structure
cogs/
├── mycog/
│   ├── __init__.py       # Empty file
│   ├── mycog.py          # Main cog file
│   ├── info.json         # Cog metadata
│   └── data/             # Optional data directory
└── anothercog.py         # Single-file cog

🧩 Master Red’s cog lifecycle for bulletproof, maintainable bot extensions that follow official best practices!

🧬 Colmena Waveform Playlist: A Deep Dive

Sun, 31 May 2026 00:00:00 +0000

🧬 Colmena Waveform Playlist: A Deep Dive #

A comprehensive guide to the colmena-waveform-playlist, a multitrack web audio editor inspired by Audacity.

🚀 Overview #

colmena-waveform-playlist is a powerful fork of the original waveform-playlist library. It’s a feature-rich, in-browser audio editor that uses the Web Audio API to provide multitrack editing capabilities with a canvas waveform preview.

Key features include:

Multitrack Editing: Load and manage multiple audio tracks.
Waveform Visualization: Renders interactive waveforms for each track.
Core Editing: Set cue points, create fades (in/out), and shift tracks in time.
Recording: Record new audio directly in the editor.
Annotations: Add time-based text annotations to tracks.
Effects: Integrate effects from the popular Tone.js library.
Export: Export the final mix as an AudioBuffer or a .wav file.

✨ Fork-Specific Features #

The ColmenaDev fork adds critical new events and functionalities not present in the original, making it a more complete editor:

🧬 Detect, Visualize & Use Valence & Arousal

Sun, 31 May 2026 00:00:00 +0000

🧬 Detect, Visualize & Use Valence & Arousal #

This guide provides a complete, practical blueprint for detecting musical emotion (Valence & Arousal), visualizing it, and using it to drive intelligent video synchronization.

🔬 Part 1: Detection with Python #

Forget training your own models. We can use essentia, a powerful audio analysis library with pre-trained models. This is the most direct path to getting emotional data from a song.