Danmaku System Design and Implementation: From Messaging Channels to Rendering Optimization

    This article describes the architecture and engineering practices of a video danmaku system. It covers a three-layer architecture consisting of access, service, and storage layers; real-time messaging over long-lived connections with heartbeats and room-scoped broadcast; persistence and querying of historical danmaku by video and time range; send-side governance such as rate limiting, content moderation, format validation, and traceability; and front-end rendering optimizations including CSS animations, track allocation, and degradation strategies for high-volume comments. It also discusses observability metrics and capacity planning. The aim is to explain the main design trade-offs—decoupling real-time broadcast from historical queries, balancing write throughput with moderation safety, and reconciling rendering smoothness with information completeness—so developers can apply these principles incrementally according to their scale.

    1. Overall Architecture of a Danmaku System

    A complete danmaku system is usually divided into three layers: the access layer, the service layer, and the storage layer.

    The access layer maintains long-lived connections between clients and servers, such as WebSocket-based channels, and handles authentication, rate limiting, and protocol encoding/decoding. The service layer handles core business logic such as sending, moderating, and broadcasting danmaku. The storage layer persists and queries historical danmaku.

    This layered design is used because each layer faces different pressure characteristics: the access layer focuses on connection count and heartbeat maintenance, the service layer focuses on throughput and business rules, and the storage layer focuses on write volume and query efficiency. After decoupling, each layer can scale independently and avoid a single bottleneck dragging down the whole system.

    1. Real-Time Messaging Channel Design

    2. Long-lived connections and heartbeats

    Danmaku has high real-time requirements. Polling becomes too expensive at large connection counts, so long-lived push connections are widely used. After a client establishes a connection with the server, periodic heartbeats keep the link alive:

    1. // Client heartbeat example
    2. setInterval(() => {
    3. socket.send(JSON.stringify({ type: 'ping', ts: Date.now() }));
    4. }, 30000);

    If the server does not receive a heartbeat within the timeout window, it should actively disconnect the connection and release resources to prevent zombie connections from accumulating.

    1. Room-scoped message broadcast

    In live streaming, danmaku broadcast is isolated by room. A common approach is to maintain a connection set for each room and iterate over the set to push new danmaku when it arrives. When a single room reaches around 100,000 users, iterating and pushing becomes a hotspot. Grouping and batch merging can reduce system calls and bandwidth usage by combining multiple danmaku from a short period into one packet for delivery.

    1. Storage for Historical Danmaku

    In VOD scenarios, after a user seeks through the video, danmaku for the corresponding time range must be displayed. Therefore, danmaku must be persisted by video and time interval.

    1. Write path

    Danmaku write volume is high, so a peak-shaving pattern is recommended: write to a message queue first, then persist asynchronously:

    1. # Service layer example: enqueue a danmaku before persistence
    2. def send_danmaku(video_id, user_id, text, ts):
    3. msg = build_payload(video_id, user_id, text, ts)
    4. mq.publish('danmaku_topic', msg) # Return quickly
    5. broadcast(video_id, msg) # Real-time broadcast
    1. Query path

    Queries usually locate data by (video_id, time_range). An efficient modeling approach is to partition by video ID and sort by second-level timestamp, together with a cache layer such as a distributed cache keyed by “video ID + minute segment” to shield hot segments from the database. Cache updates can be asynchronously refreshed by the consumer after persistence, ensuring eventual consistency.

    1. Send-Side Control and Governance

    Danmaku is typical UGC content, so multi-layer governance mechanisms are required:

    1. Rate limiting: apply server-side limits by user and by room, such as with a token bucket algorithm, and reject or silently drop requests over the limit.
    2. Content moderation: integrate sensitive-word filtering and machine moderation. Danmaku that hits risky content enters a manual review queue and is not delivered before approval.
    3. Length and format validation: perform basic validation at the gateway layer to prevent invalid data from flowing downstream.
    4. Traceability: record the sender, timestamp, and device fingerprint for each danmaku to meet audit and banning requirements.

    5. Front-End Rendering Optimization

    Danmaku rendering is a major front-end performance hotspot. The core issue is that hundreds of danmaku may be animating on the screen at the same time.

    1. Rendering channel selection

    CSS animations use the compositor layer and do not block the main thread, making them the mainstream approach for danmaku scrolling. In contrast, modifying the left property frame by frame with JavaScript triggers reflow and performs worse. Each danmaku can be created as an independent element and given a fixed-duration translate animation:

    1. .danmaku {
    2. position: absolute;
    3. animation: scroll 10s linear forwards;
    4. will-change: transform;
    5. }
    6. @keyframes scroll {
    7. from { transform: translateX(100vw); }
    8. to { transform: translateX(-100%); }
    9. }
    1. Track allocation algorithm

    To avoid danmaku overlap, several horizontal tracks must be maintained. When a new danmaku arrives, choose the track whose right end becomes free earliest. If all tracks are busy, the system can wait or allow limited overlap. The number of tracks should adapt to viewport height, and elements should be recycled promptly after danmaku leave the screen to prevent unbounded DOM node growth.

    1. Degradation strategies for massive danmaku

    When the number of historical danmaku is very large, display can be sampled by density, or the full set can be shown only when the user pauses. The system should also monitor page visibility and pause rendering and message consumption in background tabs.

    1. Observability and Capacity Planning

    After launch, the following metrics need continuous monitoring: connection count and heartbeat success rate, end-to-end message latency, queue backlog depth, persistence failure rate, front-end frame rate, and memory usage. Alert thresholds should be set based on these metrics, and load testing should be used to validate capacity boundaries such as peak users per room and connection limit per machine, providing a basis for scaling decisions.

    1. Conclusion

    A danmaku system looks simple, but it spans multiple engineering areas, including long-lived connection access, asynchronous peak shaving, cache design, content governance, and front-end rendering optimization. Key trade-offs in practice include decoupling real-time broadcast from historical queries, balancing write throughput with moderation safety, and reconciling rendering smoothness with information completeness. With these design principles, developers can incrementally build complete danmaku capabilities from a single-machine prototype to a distributed cluster according to their business scale.