What is Misaka Danmu Server#

Misaka Danmu Server is a powerful self-hosted danmaku (live comment) aggregation and management service, compatible with the dandanplay API specification. It fetches danmaku data in real-time from multiple video platforms, providing bullet comment support for your private media library (Emby, Jellyfin, Plex, etc.).

Core Features#

Intelligent Matching: Automatically match media content via filenames or metadata (TMDB, TVDB, etc.)
Web Management Interface: Intuitive UI for searching/importing danmaku, managing media sources, creating API tokens, and configuring search priorities
Danmaku Source Management: Install sources from repositories or upload offline packages, with backup/restore functionality
Metadata Integration: Integrates TMDB, TVDB, Bangumi, Douban, and IMDb
Automation Support: Supports Sonarr, Radarr, and Emby webhooks for automatic danmaku import
Multi-player Compatibility: Works with SenPlayer, Infuse, and other players supporting custom danmaku APIs

Comparison with danmu_api#

If you only need a lightweight danmaku service, check out my previous danmu_api deployment tutorial. Here’s a comparison of the two:

Feature	danmu_api	misaka_danmu_server
Basic danmaku fetching	Yes	Yes
dandanplay API compatible	Yes	Yes
Web management interface	No	Yes
Media library/metadata matching	No	Yes (TMDB/TVDB/Bangumi/Douban/IMDb)
Webhook automation	No	Yes (Sonarr/Radarr/Emby)
Danmaku source management	Limited	Yes (full source management)
Token authorization system	Simple	Yes (complete permission control)
Deployment complexity	Simple (no database)	Medium (requires MySQL)
Use case	Personal lightweight use	Complete media library management

Prerequisites#

Server Requirements#

Memory: 2GB+ recommended
Disk: 20GB+ recommended
Network: Chinese mainland IP recommended; overseas IPs may have limited access to some danmaku sources due to network or copyright restrictions

Install Docker#

If Docker is not installed, run:

If you use Dokploy, you can also use the official template. I have submitted a PR and it’s pending merge.

https://github.com/Dokploy/templates/pull/624#issuecomment-3686872830

1
curl -fsSL https://get.docker.com | sh

Docker Compose Deployment#

Create Project Directory#

1
mkdir -p ~/misaka-danmu && cd ~/misaka-danmu

Create docker-compose.yml#

1
vim docker-compose.yml

Paste the following configuration:

1
version: "3.8"
2
services:
3
  mysql:
4
    image: mysql:8.1.0-oracle
5
    container_name: danmu-mysql
6
    restart: unless-stopped
7
    environment:
8
      # !!! Important: Replace with your strong password !!!
9
      MYSQL_ROOT_PASSWORD: "your_strong_root_password"      # Database root password
10
      MYSQL_DATABASE: "danmuapi"                            # Database name
11
      MYSQL_USER: "danmuapi"                                # Database username
12
      MYSQL_PASSWORD: "your_strong_user_password"           # Database password
13
      TZ: "Asia/Shanghai"
14
    volumes:
15
      - ./db-data:/var/lib/mysql
16
    command:
17
      - '--character-set-server=utf8mb4'
18
      - '--collation-server=utf8mb4_unicode_ci'
19
      - '--binlog_expire_logs_seconds=259200' # Auto-clean binlog older than 3 days
20
      - '--default-authentication-plugin=mysql_native_password'
21
    healthcheck:
22
      test: ["CMD-SHELL", "mysqladmin ping -u$${MYSQL_USER} -p$${MYSQL_PASSWORD}"]
23
      interval: 5s
24
      timeout: 3s
25
      retries: 5
26
      start_period: 30s
27
    networks:
28
      - misaka-net
29

30
  danmu-app:
31
    image: l429609201/misaka_danmu_server:latest
32
    container_name: misaka-danmu-server
33
    restart: unless-stopped
34
    depends_on:
35
      mysql:
36
        condition: service_healthy
37
    environment:
38
      - PUID=1000
39
      - PGID=1000
40
      - UMASK=0022
41
      - TZ=Asia/Shanghai
42
      # --- Database Configuration ---
43
      - DANMUAPI_DATABASE__TYPE=mysql
44
      - DANMUAPI_DATABASE__HOST=mysql
45
      - DANMUAPI_DATABASE__PORT=3306
46
      - DANMUAPI_DATABASE__NAME=danmuapi
47
      # !!! Important: Use the same credentials as mysql container !!!
48
      - DANMUAPI_DATABASE__USER=danmuapi
49
      - DANMUAPI_DATABASE__PASSWORD=your_strong_user_password
50
      # --- Initial Admin Configuration ---
51
      - DANMUAPI_ADMIN__INITIAL_USER=admin
52
    volumes:
53
      - ./config:/app/config
54
    ports:
55
      - "7768:7768"
56
    networks:
57
      - misaka-net
58

59
networks:
60
  misaka-net:
61
    driver: bridge

Cloud Database Configuration#

If you’re using a cloud database, here’s a reference configuration:

1
version: "3.8"
2
services:
3
  danmu-app:
4
    image: l429609201/misaka_danmu_server:latest
5
    container_name: misaka-danmu-server
6
    restart: unless-stopped
7
    network_mode: "host"
8
    environment:
9
      - PUID=1000
10
      - PGID=1000
11
      - UMASK=0022
12
      - TZ=Asia/Shanghai
13
      - DANMUAPI_DATABASE__TYPE=mysql
14
      - DANMUAPI_DATABASE__HOST=10.8.0.118
15
      - DANMUAPI_DATABASE__PORT=3306
16
      - DANMUAPI_DATABASE__NAME=misaka
17
      - DANMUAPI_DATABASE__USER=misaka
18
      - DANMUAPI_DATABASE__PASSWORD=PASSWORD
19
      - DANMUAPI_ADMIN__INITIAL_USER=admin
20
    volumes:
21
      - ./config:/app/config

Replace all passwords with your own strong passwords.

Start the Service#

1
docker compose up -d

View startup logs:

1
docker compose logs -f danmu

The initial admin password will be displayed on first startup - make sure to save it:

1
[INFO] Initial admin password: xxxxxx

Initial Configuration#

Access Web Management Interface#

Open your browser and navigate to http://your-server-ip:7768

Username: admin (or your configured DANMUAPI_ADMIN__INITIAL_USER)
Password: The initial password shown in the startup logs

Danmaku Source Configuration#

Go to System Settings > Danmaku Source Management
Click Install from Repository to get the latest danmaku sources
Enable or disable specific sources as needed
Adjust source priorities

Token Management#

To allow players to access the danmaku API, you need to create a token:

Go to System Settings > Token Management
Click Create Token
Add a note (e.g., “SenPlayer”) and save
Copy the generated token for player configuration

Player Configuration#

SenPlayer#

Open SenPlayer, go to Settings > Danmaku Settings > Custom Danmaku API
Enter the API address: http://your-server-ip:7768/{Token}
- Replace {Token} with the token generated in the management interface
When playing a video, click the Danmaku button > Search Danmaku
Select your danmaku API and wait for the search to complete, then select the corresponding episode

Infuse#

Go to Settings > Metadata > Danmaku
Select Custom
Enter the API address: http://your-server-ip:7768/{Token}

Yamby (Android)#

Open Yamby, go to danmaku settings
Select custom danmaku API
Enter API address: http://your-server-ip:7768/api/v1/{Token}
Only supports manual danmaku search

Hills (Android/Windows)#

One of the most feature-complete players:

Go to Settings > Danmaku > Custom API
Enter API address: http://your-server-ip:7768/api/v1/{Token}
Supports both auto-matching and manual search

Afusekt (Android/Android TV)#

Supports dual platforms:

Go to Settings > Danmaku Settings
Select custom danmaku server
Enter API address: http://your-server-ip:7768/api/v1/{Token}

dd-danmaku (Browser Extension)#

For web-based players:

Install the browser extension
Configure API address in extension settings
Danmaku will auto-load when visiting video sites

API Path Compatibility#

The service has special route handling - all these formats work correctly:

http://IP:7768/api/v1/{Token}
http://IP:7768/api/v1/{Token}/api/v2
http://IP:7768/{Token}
http://IP:7768/{Token}/api/v2

This ensures compatibility with various players.

Advanced Configuration#

Webhook Automation#

Misaka Danmu Server supports receiving notifications from media servers via webhooks to automatically fetch danmaku.

Emby Webhook#

Install the Webhook plugin in Emby
Configure the Webhook URL: http://your-server-ip:7768/webhook/emby
Select events to trigger (e.g., new media added)

Sonarr/Radarr Webhook#

Go to Sonarr/Radarr Settings > Connect
Add a Webhook connection
URL: http://your-server-ip:7768/webhook/sonarr or /webhook/radarr
Select trigger events (e.g., download complete)

Detailed Webhook Configuration#

Jellyfin Webhook#

Install the Webhook plugin in Jellyfin
Go to Dashboard > Plugins > Webhook
Add Generic Destination
Configure Webhook URL: http://your-server-ip:7768/api/webhook/jellyfin?api_key=your_api_key
Only check Item Added event
Enable Send All Properties

Plex Webhook (via Tautulli)#

Plex native Webhook requires Plex Pass subscription and can’t handle batch imports. We recommend using free Tautulli:

Install Tautulli
Go to Settings > Notification Agents > Add Webhook
Configure Webhook URL: http://your-server-ip:7768/api/webhook/plex?api_key=your_api_key
Select Recently Added trigger
Configure JSON data template (refer to official docs)

Media Library Acquisition#

The media library acquisition feature supports reading media entries from multiple sources for automated danmaku import.

Media Server Integration#

Supports reading media libraries from Emby, Jellyfin, Plex:

Go to Settings > Media Acquisition
Select media server type
Enter server address and API Key
Click Test Connection to verify
Save to sync entries from the media server

Local Directory Scanning#

Supports scanning local folders to identify media files:

Configure local directory path
System will identify media based on filename and directory structure
Supports recursive scanning of subdirectories

Recommended directory structure:

1
Media Library/
2
├── Movies/
3
│   ├── Movie Name (2024)/
4
│   │   └── Movie Name (2024).mkv
5
│   └── ...
6
└── TV Shows/
7
    ├── Series Name/
8
    │   ├── Season 01/
9
    │   │   ├── Series Name S01E01.mkv
10
    │   │   └── Series Name S01E02.mkv
11
    │   └── Season 02/
12
    │       └── ...
13
    └── ...

Local Danmaku File Scanning#

Supports detecting and importing existing .xml danmaku files:

Configure danmaku file directory
System will scan and identify dandanplay format XML files
Auto-associate with corresponding media entries

Danmaku file naming conventions:

Movies: Movie Name (Year).xml
Episodes: Series Name S01E01.xml or Series Name Season1Episode1.xml

Metadata Source Configuration#

In System Settings > Metadata Configuration you can configure each metadata source:

TMDB (Recommended, Required)#

Visit TMDB and register
Go to Settings > API > Apply for developer access
Get API v3 key
Enter the API Key in danmaku service’s Search Settings

TVDB#

Visit TVDB and register
Go to Dashboard to generate API Key
Configure in danmaku service

Bangumi (Recommended for Anime)#

Supports two authentication methods:

Access Token: Simple method, suitable for personal use
OAuth Authentication: Suitable for multi-user scenarios

Douban#

Douban uses web scraping, no official API required. Optionally configure Cookie for better stability.

IMDb#

No authentication required, supports both third-party API and HTML parsing methods.

Priority Recommendations#

Adjust priorities based on your media library type:

General: TMDB > TVDB > Bangumi > Douban > IMDb
Anime-focused: Bangumi > TMDB > TVDB
Chinese content: Douban > TMDB > IMDb

AI Feature Configuration#

Misaka Danmu Server supports using AI to enhance matching capabilities, including intelligent matching, season mapping, and alias validation.

Supported AI Providers#

Provider	Rating	Notes
DeepSeek	⭐⭐⭐⭐⭐	Best value Chinese LLM, fast response
SiliconFlow	⭐⭐⭐⭐	Multiple open-source models, China-friendly
OpenAI	⭐⭐⭐	Good results, but requires proxy in China
Google Gemini	⭐⭐⭐	Good results, but requires proxy in China

Configuration Steps#

Go to Settings > AI-Assisted Enhancement
Select AI provider
Enter API Key
Set Base URL (usually use default)
Select model name
Click Test Connection to verify

Cost reference: DeepSeek charges ¥1/million tokens input, ¥2/million tokens output. Since each call uses very few tokens, monthly costs are typically just a few yuan.

Telegram Bot#

You can manage the danmaku service remotely via Telegram Bot, supporting search/import, library management, task monitoring, and more.

balge

misaka-danmuku-bot

Waiting for api.github.com...

00K

Waiting...

Requirement: Danmaku library version > v2.0.4

Refer to the project documentation for detailed configuration.

Danmaku Source Management#

Online Repository Installation#

Go to System Settings > Danmaku Source Management
Configure repository URL (supports GitHub or CDN acceleration):

1
https://github.com/l429609201/Misaka-Scraper-Resources

Click Install from Repository
System will auto backup current sources, download latest files, install and reload

Offline Package Installation#

If you can’t access online repositories:

Download the platform-specific offline package from Releases page
Upload the offline package in Web UI
System will auto install and reload

Backup and Recovery#

Auto Backup: System auto-backups current sources during updates
Manual Backup: Click backup button on source management page
Recovery: Select backup file to restore

Danmaku Library Management#

Entry Management#

On the Danmaku Library page you can:

View, edit, delete entries
Search by title
Filter by type (movies, TV shows, anime, etc.)

Each entry contains:

Basic info (title, year, etc.)
Alias list
Multiple danmaku sources (Bilibili, iQiyi, etc.)

Manual Entry Creation#

For works not in danmaku sources, you can manually create entries:

Click New Entry
Fill in work information
Can import local XML danmaku files

XML Danmaku Import#

Supports importing dandanplay format danmaku files:

Single file import: Select individual XML file
Batch import: Select multiple XML files

TMDB Auto Enhancement#

When enabled, the system will automatically add aliases to entries via TMDB scheduled tasks, improving player matching success rate.

Danmaku API Feature Configuration#

Advanced Token Settings#

When creating tokens, you can configure:

Validity period: Token expiration time
Daily call limit: Prevent abuse

Danmaku Output Settings#

Sampling limit: Recommended 3000-5000 (desktop), lower for mobile
Random colors: Assign random colors to danmaku
Blacklist filtering: Supports keywords and regex

Custom Storage Path#

You can use variables to customize danmaku storage paths:

${title} - Work title
${season} - Season
${episode} - Episode number
${episodeId} - Episode ID

Auto Fallback Options#

Match fallback: Auto fetch from sources when local results unavailable
Search fallback: Try backup sources when primary source has no results
Sequential fallback: Try other sources when primary source has no valid episodes
Pre-download: Auto download next episode danmaku in background

Command System#

You can use special commands in the search interface (case-insensitive):

Command	Description
`@`	View available commands
`@QLHC`	Clear cache
`@SXDM`	Refresh danmaku (multi-step selection)
`@CXLK`	Check rate-limiting status
`@CXRW`	Query task status

Filter Configuration#

Entry Title Filtering#

On search results page, you can filter entries by keywords:

Supports partial matching
Case-insensitive
Supports mixed Chinese and English

Episode Name Filtering#

On entry detail page, you can filter episode lists:

S01, Season 1 - Filter by season
E05, Episode 5 - Filter by episode
Special, OVA - Filter special content

Reverse Proxy Configuration#

To access via domain name, configure an Nginx reverse proxy:

1
server {
2
    listen 443 ssl http2;
3
    server_name danmu.example.com;
4

5
    ssl_certificate /path/to/cert.pem;
6
    ssl_certificate_key /path/to/key.pem;
7

8
    location / {
9
        proxy_pass http://127.0.0.1:7768;
10
        proxy_set_header Host $host;
11
        proxy_set_header X-Real-IP $remote_addr;
12
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
13
        proxy_set_header X-Forwarded-Proto $scheme;
14

15
        # WebSocket support
16
        proxy_http_version 1.1;
17
        proxy_set_header Upgrade $http_upgrade;
18
        proxy_set_header Connection "upgrade";
19
    }
20
}

After configuration, update the API address in your player to https://danmu.example.com/{Token}.

Updating the Service#

1
cd ~/misaka-danmu
2
docker compose pull
3
docker compose up -d

Important Notes#

Network Environment#

Deploying with a Chinese mainland IP is recommended; overseas servers may have limited access to some danmaku sources due to network restrictions
If using an overseas server, you may need to configure a proxy

Fair Use#

The project author explicitly states in the documentation:

All danmaku data is obtained from third-party public APIs or websites. Please use responsibly and avoid abuse that may result in IP bans.

Disclaimer#

Misaka Danmu Server only provides danmaku data aggregation, storage, and API access functionality. It does not produce, modify, store, or distribute video content itself. Users are responsible for their own usage.

Docker Deployment Guide for Misaka Danmu Server