tiny-bilibili-ws

library1.0.2jsnpmunverified

A lightweight, TypeScript-first WebSocket/TCP client for Bilibili live streaming API, supporting both Node.js and browser environments. Current stable version is 1.0.2, released in 2022. It provides an event-driven interface for receiving live room data like danmaku (DANMU_MSG), heartbeat, and other Bilibili live events. Unlike heavier alternatives, it is minimal and includes built-in TypeScript type definitions. Requires manual cookie/UID for anti-spoofing and extra key/url for browser usage due to CORS restrictions.

messaging

npm install tiny-bilibili-ws

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · TINY-BILIBILI-WS

tiny-bilibili-ws

messagingjavascriptv1.0.2

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

KeepLiveWS

✓ import { KeepLiveWS } from 'tiny-bilibili-ws'

✗ const { KeepLiveWS } = require('tiny-bilibili-ws')

Default export is not available; use named import. ESM-only package; CommonJS require will fail.

toMessageData

✓ import { toMessageData } from 'tiny-bilibili-ws'

✗ import { toMessageData } from 'tiny-bilibili-ws/browser'

toMessageData is exported from the main entry, not from /browser. The browser path is only for KeepLiveWS.

KeepLiveWS (browser)

✓ import { KeepLiveWS } from 'tiny-bilibili-ws/browser'

✗ import { KeepLiveWS } from 'tiny-bilibili-ws'

For browser environments, use the /browser subpath import. The main path is for Node.js only.

Connects to a Bilibili live room and logs danmaku messages and heartbeat online count.

import { KeepLiveWS, toMessageData } from 'tiny-bilibili-ws' const room = 652581 const live = new KeepLiveWS(room, { headers: { Cookie: 'your_cookie_here', }, uid: 0, }) live.on('DANMU_MSG', (danmu) => { console.log(toMessageData(danmu)) }) live.on('heartbeat', (online) => { console.log('人气值: ', online) }) live.on('error', (e) => { console.error('错误: ', e) })

Debug

Known issues

gotchaBrowser usage requires manual passing of 'url' and 'key' options due to CORS restrictions. The default API endpoints are not accessible from the browser.

fix

Fetch the key and url from your own server or proxy and pass them as options: new KeepLiveWS(room, { url: 'wss://...', key: '...' })

affects: >=1.0.0

gotchaIf you do not provide a valid Cookie and uid, the DANMU_MSG event will not include sender username (data.user will be undefined).

fix

Provide a valid Bilibili Cookie and corresponding uid in the options object.

affects: >=1.0.0

breakingThe package is ESM-only. Using require() will throw a Module not found error.

fix

Use import syntax or configure your project for ESM.

affects: >=1.0.0

deprecatedThe 'runWhenConnected' method is synchronous and may not reliably wait for connection. Consider using the 'open' event instead.

fix

Use live.on('open', () => {...}) as a more reliable alternative.

affects: >=1.0.0

gotchaHeartbeat event returns 'online' as a number, but some rooms may return NaN or 0. Always validate the value.

fix

Check typeof online === 'number' && !isNaN(online) before using.

affects: >=1.0.0

gotchaThe package depends on the 'ws' module for Node.js, which must be installed separately if your runtime does not include it.

fix

Run 'npm install ws' if you encounter errors about missing 'ws'.

affects: >=1.0.0

Errors

Common errors & fixes

Module not found: Error: Can't resolve 'tiny-bilibili-ws'

Using require() on an ESM-only package or missing npm install.

fix

Install the package with 'npm install tiny-bilibili-ws' and use import syntax.

WebSocket connection to 'wss://broadcastlv.chat.bilibili.com/sub' failed: Error in connection establishment: net::ERR_CONNECTION_REFUSED

In browser environment without providing url and key options.

fix

When using in browser, pass url and key options: new KeepLiveWS(room, { url: '...', key: '...' })

TypeError: Cannot read properties of undefined (reading 'user')

Missing or invalid Cookie and uid when receiving DANMU_MSG.

fix

Provide a valid Bilibili Cookie and uid in the KeepLiveWS options.

Upgrade

Version history

1.0.2latest on npm

Audit

Dependencies

wsoptionalWebSocket implementation for Node.js; optional in browser builds

Agent activity

23 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/starknt/tiny-bilibili-ws ↗

packagetiny-bilibili-ws ↗

homepagehttps://github.com/starknt/tiny-bilibili-ws#readme ↗