Skip to content

Home

Jump to bottom
teuk edited this page May 30, 2026 · 33 revisions

Mediabot v3

Mediabot v3 is a multi-purpose IRC bot written in Perl.

It is used for real IRC operations: channel administration, user management, command dispatching, public utility commands, analytics, URL/media helpers, Partyline administration, testing, monitoring, and long-running bot maintenance.

This wiki documents the current project state, with a strong focus on:

  • fresh installation;
  • safe upgrades;
  • configuration;
  • database validation;
  • command usage;
  • Partyline operation;
  • troubleshooting;
  • testing and release discipline.

Current documentation status

The wiki is being rebuilt around the current Mediabot v3 development tree and the real installation/testing workflow.

The project versioning policy remains:

  • odd minor versions are stable releases;
  • even minor versions are development / beta lines.

Examples:

  • 3.1 = stable release;
  • 3.2-dev = current development line;
  • 3.3 = next stable release target.

If you are installing from the Git repository, follow the development-tree documentation and validate with the test suite.

Start here

Install Mediabot

Start with:

This page should explain the full fresh install path, including Debian dependencies, database creation, ./configure, first start, login/register checks, and post-install validation.

Configure Mediabot

Read:

This page documents the current mediabot.sample.conf model, including database, connection, OpenAI/Claude, Chromium, metrics, radio, Partyline, antiflood, retention, and runtime settings.

Understand the database

Read:

This page documents the fresh-install schema from install/mediabot.sql, the major table groups, important relationships, and how this differs from existing upgraded production databases.

For upgrades and existing databases, also read:

Commands

Public IRC commands

Use this page for normal channel commands available to public users, depending on channel settings and enabled integrations.

Private, admin, and privileged commands

Use this page for authentication, user/channel administration, privileged commands, and owner/master/admin operations.

Command levels

Use this page to answer:

What can this user level actually do?

Operations

Running with systemd

Use this page to run Mediabot as one or more systemd-managed instances. It covers the mediabot@.service template, /etc/default/mediabot-<instance> files, multi-instance layouts, logs, restarts, and temporary maintenance pauses.

Monitoring with Prometheus and Grafana

Use this page to enable Mediabot metrics, configure Prometheus scraping, and import the hourly Grafana dashboard from contrib/grafana/.

Radio integration

Use this page to understand the Liquidsoap/Icecast radio stack, MP3 cache-first playback, yt-dlp download safety, radiocheck, radio admin commands, and the current YouTube cookies limitations.

Partyline

The Partyline is the TCP admin interface. It is useful for runtime inspection, console output, controlled operations, DCC CHAT, antiflood diagnostics, netsplit diagnostics, and administrative commands.

Testing

Use this page before committing, before deploying, and after a fresh install. It should document static tests, live tests, full test runs, log locations, and how to interpret failures.

Troubleshooting

Use this page when something breaks during install, startup, runtime, Partyline, IRC handling, database validation, URL title handling, antiflood, or migrations.

Maintainer notes

These pages are mainly for maintainers and contributors:

The command audit is not a user guide. It is a consistency check between command dispatch and internal help documentation.

Recommended reading order

For a fresh install:

  1. Installation
  2. Configuration
  3. Database model
  4. Testing
  5. Troubleshooting

For an operator:

  1. Configuration
  2. Public commands
  3. Private and admin commands
  4. Command level index
  5. Running with systemd
  6. Partyline
  7. Troubleshooting

For a maintainer:

  1. Testing
  2. Database model
  3. Release and upgrade notes
  4. Command documentation audit

Documentation cleanup roadmap

The wiki is being cleaned in phases:

  1. create missing structural pages such as Database-model.md;
  2. rebuild Home.md and navigation;
  3. regenerate command pages from the current source;
  4. rewrite Configuration.md from mediabot.sample.conf;
  5. update Installation.md after a fresh Debian install test;
  6. update Testing.md around the current full test workflow;
  7. update Partyline.md with current commands and diagnostics;
  8. enrich Troubleshooting.md with real issues encountered during development.

Quick links

Mediabot 3.3 · Release and upgrades · Installation · Configuration · Testing · Troubleshooting

Mediabot v3 Wiki

Start here

Use the bot

Operate the bot

Extend the bot

Reference and maintenance

Clone this wiki locally