Document 02 / 03
Streaming Implementation Guide
Deep-dive into how live streaming is wired in Tunnel today: the RTMP/HLS servers, the stream lifecycle (create → go live → watch → end), Socket.IO events, the FFmpeg recorder, and the exact bugs that currently prevent streaming from working end-to-end.
1. Components (verified)#
| Component | Where | Port / Role |
|---|---|---|
| Express API | backend/src/server.js | 5000 — REST + Socket.IO |
| Node-Media-Server | server.js (nmsConfig) | RTMP ingest 1935, HLS/HTTP 8080, mediaroot: ./media |
| Socket.IO | server.js + sockets.js | realtime events, cors: { origin: "*" } |
| FFmpeg recorder | utils/ffmpeg-recorder.js | optional MP4 + HLS recording of an RTMP source |
Node-Media-Server config (server.js:20-33)#
nmsConfig = {
rtmp: { port: 1935 (env RTMP_PORT), chunk_size: 60000, gop_cache: true, ... },
http: { port: 8080 (env HLS_PORT), mediaroot: "./media", allow_origin: "*" },
}
NMS auto-starts only if both ports are free; otherwise the Express server still runs (warn log).
Key fact: NMS serves HLS at
http://localhost:8080/live/{streamKey}/index.m3u8(stream path/live/{key}), NOT/hls/{key}.m3u8. Several backend responses get this wrong (see §4).
2. Intended lifecycle (as designed in code)#
Creator clicks "Go Live" (golive.jsx)
1. POST /api/v1/streams/create { title, description, category } [requireAuth + role creator/admin + zod]
→ Stream doc created: { streamKey: uuid, isLive: false, rtmpUrl: rtmp://localhost:1935/live/{key} }
→ returns { _id, streamKey, rtmpUrl, hlsUrl }
2. Frontend opens socket to localhost:5000, emits "join-stream" { _id }
3. Creator points OBS at rtmp://localhost:1935/live/{streamKey}
→ NMS prePublish fires (logs only today) → intended to set isLive=true, start recording
4. Viewers: GET /api/v1/streams/live → list of isLive:true streams
→ Watch page /stream/:id → GET /api/v1/streams/:id → stream.hlsUrl
→ StreamPlayer (hls.js) plays http://localhost:8080/live/{key}/index.m3u8
5. Socket "send-message" persists chat; "stream-metrics" updates bitrate/fps; viewer counts track joins/leaves
6. End: PUT /api/v1/streams/end/:id → isLive=false, endedAt set → socket "stream-ended"
None of steps 3–6 work today. Step 1 fails outright (CastError — see §4.1), which cascades into everything else.
3. Socket.IO events (sockets.js — implemented, mostly unused by the app)#
| Event (client → server) | Behavior |
|---|---|
join-stream {streamId} | adds viewer to room, bumps activeStreams metrics, Stream.findByIdAndUpdate(streamId, {viewers}), emits viewer-count + stream-status |
send-message {streamId, message, userId, userName, sender} | moderation → rate limit (10/min/user) → slow mode → keyword filter → AI moderation → Message.create → broadcast receive-message |
stream-metrics {streamId, bitrate, fps, resolution} | updates in-memory metrics, computes health, broadcasts |
stream-started {streamId, rtmpUrl, creatorId} | sets isLive:true + startedAt, starts FFmpeg recording if rtmpUrl given |
stream-ended {streamId} | stops recording, sets isLive:false, endedAt, duration, broadcasts |
leave-stream {streamId} | decrements viewer count |
disconnect | cleans viewer from all active streams |
Critical gap: nothing in golive.jsx (or anywhere in the frontend) ever emits stream-started or stream-ended. The server-side handlers exist but are never triggered. golive.jsx only emits join-stream / leave-stream and calls the REST endpoints.
4. Verified bugs that break streaming (with exact locations)#
4.1 P0 — POST /streams/create always fails (CastError)#
stream.controller.js:24
const stream = await Stream.create({
...
creator: userId, // userId = req.auth.userId → "user_2abc..." (Clerk string)
...
});
Stream.creator is mongoose.Schema.Types.ObjectId + required. Saving a Clerk string → CastError → 500. No stream can ever be created.
Fix: resolve the Mongo user first:
const user = await User.findOne({ clerkId: userId }).select("_id").lean();
if (!user) return res.status(404).json({ error: "User not found" });
// then: creator: user._id
Also do the same lookup in getLiveStreams/getStreamById populate("creator") path — populate over a stored invalid ObjectId would throw, and over a valid ObjectId it correctly returns {username, avatarUrl}.
4.2 P0 — isLive never becomes true#
Three independent reasons:
goLivecontroller (stream.controller.js:49) is not mounted on any route — dead code.- Frontend never emits socket
stream-started(the handler at sockets.js:225 is the only place that setsisLive:true). - NMS
prePublish/donePublish(server.js:56-61) onlyconsole.log— they don't update the DB or trigger any API.
Result: /streams/live is always [], so Explore/Dashboard/Watch show no live streams even when OBS is publishing.
Fix (choose one):
- Option A (simple): in
golive.jsx, aftercreateStreamsucceeds,socket.emit("stream-started", { streamId, rtmpUrl, creatorId }). On end, emitstream-ended. This immediately activates the existing server handlers. - Option B (robust, recommended): use NMS
prePublish/donePublishto call the API/webhook, validate the stream key against the DB (Stream.findOne({ streamKey })), setisLive/startedAt/endedAt, and notify viewers via Socket.IO. This also fixes the "anyone can publish to any key" hole.
4.3 P0 — Wrong HLS URL returned to viewers#
stream.controller.js:33 and :131 return http://localhost:8080/hls/{streamKey}.m3u8, but NMS's real URL is http://localhost:8080/live/{streamKey}/index.m3u8. The Watch page (components/profile/stream.jsx:118) passes stream.hlsUrl to StreamPlayer as overrideHlsUrl, so the player loads a 404 manifest. (The creator's own preview in golive.jsx:151 uses the correct URL — which is why only the creator can ever see their stream today.)
Fix: change both controllers to http://${HLS_HOST}/live/${streamKey}/index.m3u8 (env-driven). The /hls/{key}.m3u8 default URL inside StreamPlayer.jsx is already correct — make sure stream.hlsUrl from the backend is correct too, or stop overriding it.
4.4 P1 — Chat messages never persist (CastError)#
sockets.js:165 Message.create({ chatMessage, sender: userId /* clerk string */, category: streamId /* Mongo id string */ }) — both sender and category are ObjectId fields in ChatMessage.models.js → CastError → message silently dropped (send-message catch logs and returns).
Also getChatMessages (chat.controller.js:126) does Message.find({ category: streamId }) with a raw string → same CastError for non-ObjectId streamIds.
Fix: store resolved ObjectIds (convert userId and streamId before saving), or change the ChatMessage schema so sender is a String (Clerk ID) and category is a String (stream ID) — simpler and consistent with how the frontend already treats them.
4.5 P1 — Recording never starts#
startRecording is called only from the stream-started socket event (never emitted). Even when it runs, ffmpeg-recorder.js writes to backend/recordings, backend/hls, backend/vod and stores recordingUrl: /vod/..., but no express.static serves these directories — recorded files would be unreachable. (Also note: rtmpUrl passed to FFmpeg should be the publish URL, e.g. rtmp://localhost:1935/live/{key}.)
Fix: emit stream-started (per §4.2), then add:
app.use("/media", express.static("media"));
app.use("/hls", express.static("hls"));
app.use("/vod", express.static("vod"));
app.use("/recordings", express.static("recordings"));
4.6 P1 — VOD route missing#
Frontend vodAPI.getAll() → GET /api/v1/streams/vod/all. stream.route.js has no such route (the real ones are /creator/:creatorId/recordings). → 404, VOD page is empty.
Fix: add GET /vod/all (or point vodAPI at /creator/{id}/recordings), and fix getStreamRecordings so it returns public VODs with correct vodUrl/hlsUrl.
4.7 P1 — Hardcoded localhost in URLs#
- Controllers:
rtmp://localhost:1935/live/...,http://localhost:8080/hls/...(createStream, getStreamById, getStreamRecordings). - Frontend:
io("http://localhost:5000")ingolive.jsx,profile/stream.jsx,DashboardPage.jsx, and the stream/explore layouts;StreamPlayerdefaulthttp://localhost:8080/live/....
Fix: introduce env-driven base URLs — backend HLS_BASE_URL/RTMP_BASE_URL; frontend VITE_API_URL, VITE_SOCKET_URL, VITE_HLS_URL — and stop interpolating localhost.
4.8 P1 — No NMS stream-key validation / on_publish#
Anyone with a stream key (or any key at all — it's not checked) can publish. There's no correlation between the RTMP publish event and the authenticated creator who owns the key.
Fix: in nms.on("prePublish", (id, StreamPath) => { ... }), extract the key from StreamPath, look up Stream.findOne({ streamKey: key }), verify the creator's session, then set isLive/startedAt, start recording, and notify via socket.
4.9 P2 — Socket.IO is unauthenticated and trusts client userId#
Server(server, { cors: { origin: "*" } }); send-message trusts data.userId from the client — spoofable. No io.use() auth hook.
Fix: connect with io("...", { auth: { token: await getToken() } }), add a socket middleware that verifies via Clerk, and use socket.data.userId server-side instead of the client value.
5. What the correct flow should look like (target implementation)#
1. POST /streams/create (requireAuth, role creator/admin)
creatorId = User.findOne({clerkId})._id
stream = Stream.create({ creator: creatorId, streamKey: uuid, isLive: false })
return { _id, streamKey, rtmpUrl: `${RTMP_BASE_URL}live/${streamKey}`, hlsUrl: `${HLS_BASE_URL}live/${streamKey}/index.m3u8` }
2. golive.jsx connects socket (with Clerk token in auth), emits "stream-started" { streamId, rtmpUrl }
3. OBS publishes rtmp://host:1935/live/{streamKey}
NMS prePublish → validate key → Stream.updateOne({ streamKey }, { isLive: true, startedAt: now })
→ startRecording(streamId, rtmpUrl) → socket broadcast "stream-status: live"
4. Viewers:
GET /streams/live → isLive:true docs, populate creator (ObjectId refs now valid)
GET /streams/:id → { ..., hlsUrl: `${HLS_BASE_URL}live/${key}/index.m3u8` }
StreamPlayer plays that hlsUrl (or its own default)
5. Real-time: join-stream/leave-stream adjust viewers; stream-metrics update health;
send-message persists with ObjectId refs; all events authenticated.
6. End stream:
socket "stream-ended" { streamId } (or NMS donePublish)
→ stopRecording, Stream.updateOne({ isLive:false, endedAt, recordingDuration, isRecorded:true })
→ broadcast ended → activeStreams cleanup after 5 min
6. Files involved#
backend/src/server.js— NMS config, port checks, server bootbackend/src/sockets.js— all socket event handlers +activeStreamsbackend/src/controller/stream.controller.js— create/goLive/end/live/byId/recordings/search/trendingbackend/src/route/stream.route.js— REST endpoints (note:goLivenot routed)backend/src/utils/ffmpeg-recorder.js— MP4 + HLS recorderbackend/src/middleware/validate.js—streamCreateSchema(title ≥3, description ≥10, category ≥2)Frontend/src/components/pages/golive.jsx— creator dashboardFrontend/src/components/pages/StreamPlayer.jsx— hls.js playerFrontend/src/components/profile/stream.jsx— watch pageFrontend/src/components/ui_layout/ui_layout_stream.jsx—/Watchlayout (picks stream via?stream=)
7. Test plan (once fixed)#
npm run devinbackend/src,npm run devinFrontend.- Sign in, go to
/Live, enter a title → Go Live → confirm a Stream doc appears withisLive:true. - Open OBS → Settings → Stream → Server
rtmp://localhost:1935/live, Key<streamKey>→ Start Streaming. - Confirm creator preview plays (hls.js, correct
/live/{key}/index.m3u8URL). - Second browser:
/Exploreshows the stream;/Watch?stream=<id>plays video; chat send/recv persists (Messagedocs appear); viewer count increments. - End stream →
isLive:false,endedAtset; recording file appears underbackend/recordingsand is served. - Analytics: a
createAnalyticscall on stream start/end populates data so the report endpoint returns real numbers.
Priority order: fix §4.1 → §4.2 → §4.3, and streaming works end-to-end for the first time. See project_Status.md for the full bug list and AUTHENTICATION_GUIDE.md for the auth fixes these stream routes depend on.