DanmakuClient

Overview

DanmakuClient is the only open API to applications. In most cases, the need could be met using only this class explicitly and with help of other pages in this Wiki. Therefore, documentation of other classes in bilibili-danmaku-client is not listed in the Wiki. Reading the code is preferred.

DanmakuClient class

    class DanmakuClient {
        room: Number,
        state: String,
    }

• property room: The id of the Live Room that this DanmakuClient listens to.
• property state: The state of this DanmakuClient. See lifecycle.

new DanmakuClient() constructor

    new DanmakuClient(room: Number, options: any)

Construct a new DanmakuClient instance.

• param room: The id of the Live Room that the new DanmakuClient listens to.
  • Note that the Room id must be the original Room id, that is, the short Room id is not accepted.
  • For example, one of the official Live Rooms, https://live.bilibili.com/1, possesses the original Room id 5440.
  • In this case, trying to connect to Room 1 would not work properly, the correct way is to connect to Room 5440.
  • One way to get the original Room id is, type window.BilibiliLive.ROOMID into the console of an opened Live Room Page.
• param options: The options to setup the DanmakuClient.
  • This param is unnecessary in most cases.
  • You should know that you're doing if you are using this.
  • See in-code documentation for details.

DanmakuClient.prototype.start()

    function start(): void

Starts this DanmakuClient.

Before invoking this method, the connection is not actually started, which leaves time for applications to do configuration on the DanmakuClient instance. Meanwhile, the state property remaing idle. See lifecycle for more information.

This method returns immediately. Listen to the open event to act on the opening of the Client. See events for more information.

Calling this method when the state is not idle will have no effect.

DanmakuClient.prototype.terminate()

    function terminate(): void

Requests termination of thie DanmakuClient.

In opening and opened state, this method can be used to request the DanmakuClient to terminate. Otherwise, this method will have no effect.

Thie method returns immediately. Listen to the close event to act on the termination of the Client. See events for more information.

Danmaku.prototype.on()

    function on(name: string, listener: Function): void

Add an listener which listens to event with given name on this DanmakuClient.

If multiple listeners have been bound to the same event, they will be invoked in bound order. If a listener throws an Error, behavior of other listeners will be undefined.

The listener function is invoked with a list of zero or more parameters. The number and type of parameters is defined by the type of event.

For a list of listenable events and their parameters, see events.

• param name: The name of event to listen to.
• param listener: The listener used to listen to the event.

ApplicationEvent class

    class ApplicationEvent {
        name: String,
        content: any,
    }

An ApplicationEvent instance represents an Application Event.

It is used as the parameter type of event event, and is a simple data class with no method.

The content property contains data specific to the type of the Application Event. Applications can use name to determine the type and read content accordingly. See Events for a list of Application Events and structure of their corresponding content property.

Note that the ApplicationEvent class is not exported by bilibili-danmaku-client, so something instanceof ApplicationEvent will not work.

Also note that the Application Event is not same to the event listened by DanmakuClient.prototype.on(). The Application Event is defined in the Application Protocol.

• property name: The name of this ApplicationEvent, used to distinguish between different types of Application Events.
• property content: The content of the Application Event.

Lifecycle

DanmakuClient has the following states:

1. Idle State: When the connection is not yet started.
2. Opening State: When the connection is opening.
3. Opened State: When the connection is established is ready to receive data.
4. Closing State: When the connection is closing, after client.termiante() is called and closing is reqested.
5. Closed State: When the connection is closed.

The states transfers as follows:

• Start from Idle State: Right after new DanmakuClient().
• From Idle State:
  • to Opening State: When client.start() is called.
• From Opening State
  • to Closing State: When client.terminate() is called before the connection is opened.
  • to Closed State: When an error occurs while opening. Emit event close. Emit event error with the error thrown.
  • to Closed State: When the connection is closed by the Server. Emit event 'close'.
  • to Opened State: When the connection is successfully established. Emit event open.
• From Opened State
  • to Closing State: When client.terminate() is called.
  • to Closed State: When an error occurs. Emit event close. Emit event error with the error thrown.
• From Closing State:
  • to Closed State: When connection is successfully closed. Emit event close.
• End in Closed State.

Events

Event open

Emitted when the connection with the Server is successfully established and the DanmakuClient is ready to receive ApplicationEvents.

At this event, the state of the DanmakuClient is always opened.

This event has no param.

Event close

Emitted when the connection is closed.

After closing, the DanmakuClient instance cannot be reused, and applications should open a new one to support keeping alive.

At this event, the state of the DanmakuClient is always closed.

This event has no param.

Event error

Emitted when an error occurs.

An error can occur in both opening and opened state. An error is mostly network failure.

An error event is always emitted after an close, and at this event, the state of the DanmakuClient is always closed.

This event has a param of type Error.

Event event

Emitted when an ApplicationEvent is received from the Server.

At this event, the state of this DanmakuClient is always opened.

This event has a param of type ApplicationEvent, which is the event received from the Server.