{"id":49520,"library":"tiny-bilibili-ws","title":"tiny-bilibili-ws","description":"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.","status":"active","version":"1.0.2","language":"javascript","source_language":"en","source_url":"https://github.com/starknt/tiny-bilibili-ws","tags":["javascript","ws","websocket","bilibili","live","typescript"],"install":[{"cmd":"npm install tiny-bilibili-ws","lang":"bash","label":"npm"},{"cmd":"yarn add tiny-bilibili-ws","lang":"bash","label":"yarn"},{"cmd":"pnpm add tiny-bilibili-ws","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"WebSocket implementation for Node.js; optional in browser builds","package":"ws","optional":true}],"imports":[{"note":"Default export is not available; use named import. ESM-only package; CommonJS require will fail.","wrong":"const { KeepLiveWS } = require('tiny-bilibili-ws')","symbol":"KeepLiveWS","correct":"import { KeepLiveWS } from 'tiny-bilibili-ws'"},{"note":"toMessageData is exported from the main entry, not from /browser. The browser path is only for KeepLiveWS.","wrong":"import { toMessageData } from 'tiny-bilibili-ws/browser'","symbol":"toMessageData","correct":"import { toMessageData } from 'tiny-bilibili-ws'"},{"note":"For browser environments, use the /browser subpath import. The main path is for Node.js only.","wrong":"import { KeepLiveWS } from 'tiny-bilibili-ws'","symbol":"KeepLiveWS (browser)","correct":"import { KeepLiveWS } from 'tiny-bilibili-ws/browser'"}],"quickstart":{"code":"import { KeepLiveWS, toMessageData } from 'tiny-bilibili-ws'\n\nconst room = 652581\nconst live = new KeepLiveWS(room, {\n  headers: {\n    Cookie: 'your_cookie_here',\n  },\n  uid: 0,\n})\n\nlive.on('DANMU_MSG', (danmu) => {\n  console.log(toMessageData(danmu))\n})\n\nlive.on('heartbeat', (online) => {\n  console.log('人气值: ', online)\n})\n\nlive.on('error', (e) => {\n  console.error('错误: ', e)\n})","lang":"typescript","description":"Connects to a Bilibili live room and logs danmaku messages and heartbeat online count."},"warnings":[{"fix":"Fetch the key and url from your own server or proxy and pass them as options: new KeepLiveWS(room, { url: 'wss://...', key: '...' })","message":"Browser usage requires manual passing of 'url' and 'key' options due to CORS restrictions. The default API endpoints are not accessible from the browser.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Provide a valid Bilibili Cookie and corresponding uid in the options object.","message":"If you do not provide a valid Cookie and uid, the DANMU_MSG event will not include sender username (data.user will be undefined).","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Use import syntax or configure your project for ESM.","message":"The package is ESM-only. Using require() will throw a Module not found error.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Use live.on('open', () => {...}) as a more reliable alternative.","message":"The 'runWhenConnected' method is synchronous and may not reliably wait for connection. Consider using the 'open' event instead.","severity":"deprecated","affected_versions":">=1.0.0"},{"fix":"Check typeof online === 'number' && !isNaN(online) before using.","message":"Heartbeat event returns 'online' as a number, but some rooms may return NaN or 0. Always validate the value.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Run 'npm install ws' if you encounter errors about missing 'ws'.","message":"The package depends on the 'ws' module for Node.js, which must be installed separately if your runtime does not include it.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"search_vec":"'1.0.2':27 '2022':30 'altern':55 'anti':72 'anti-spoof':71 'api':16 'bilibili':3,13,50,87 'browser':21,78 'built':62 'built-in':61 'client':11 'cookie/uid':69 'cor':82 'current':23 'danmaku':44 'danmu':45 'data':42 'definit':66 'driven':36 'due':80 'environ':22 'event':35,52 'event-driven':34 'extra':75 'first':9 'heartbeat':47 'heavier':54 'includ':60 'interfac':37 'javascript':84 'key/url':76 'lightweight':6 'like':43 'live':14,40,51,88 'manual':68 'minim':58 'msg':46 'node.js':19 'provid':32 'receiv':39 'releas':28 'requir':67 'restrict':83 'room':41 'spoof':73 'stabl':24 'stream':15 'support':17 'tini':2 'tiny-bilibili-w':1 'type':65 'typescript':8,64,89 'typescript-first':7 'unlik':53 'usag':79 'version':25 'websocket':86 'websocket/tcp':10 'ws':4,85","created_at":"2026-06-07T17:02:11.204374+00:00","updated_at":"2026-06-07T17:02:11.204374+00:00","problems":[{"fix":"Install the package with 'npm install tiny-bilibili-ws' and use import syntax.","cause":"Using require() on an ESM-only package or missing npm install.","error":"Module not found: Error: Can't resolve 'tiny-bilibili-ws'"},{"fix":"When using in browser, pass url and key options: new KeepLiveWS(room, { url: '...', key: '...' })","cause":"In browser environment without providing url and key options.","error":"WebSocket connection to 'wss://broadcastlv.chat.bilibili.com/sub' failed: Error in connection establishment: net::ERR_CONNECTION_REFUSED"},{"fix":"Provide a valid Bilibili Cookie and uid in the KeepLiveWS options.","cause":"Missing or invalid Cookie and uid when receiving DANMU_MSG.","error":"TypeError: Cannot read properties of undefined (reading 'user')"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":"https://github.com/starknt/tiny-bilibili-ws#readme","github":"https://github.com/starknt/tiny-bilibili-ws","docs":null,"changelog":null,"pypi":null,"npm":"tiny-bilibili-ws","openapi_spec":null,"status_page":null,"smithery":null,"categories":["messaging"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-07","next_check":"2026-09-05","install_tag":null}}