Document 02 / 03

Streaming Implementation Guide

Version 2.0August 14, 20267 min readSource on GitHub

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)#

ComponentWherePort / Role
Express APIbackend/src/server.js5000 — REST + Socket.IO
Node-Media-Serverserver.js (nmsConfig)RTMP ingest 1935, HLS/HTTP 8080, mediaroot: ./media
Socket.IOserver.js + sockets.jsrealtime events, cors: { origin: "*" }
FFmpeg recorderutils/ffmpeg-recorder.jsoptional 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
disconnectcleans 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:

  1. goLive controller (stream.controller.js:49) is not mounted on any route — dead code.
  2. Frontend never emits socket stream-started (the handler at sockets.js:225 is the only place that sets isLive:true).
  3. NMS prePublish/donePublish (server.js:56-61) only console.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, after createStream succeeds, socket.emit("stream-started", { streamId, rtmpUrl, creatorId }). On end, emit stream-ended. This immediately activates the existing server handlers.
  • Option B (robust, recommended): use NMS prePublish/donePublish to call the API/webhook, validate the stream key against the DB (Stream.findOne({ streamKey })), set isLive/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") in golive.jsx, profile/stream.jsx, DashboardPage.jsx, and the stream/explore layouts; StreamPlayer default http://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 boot
  • backend/src/sockets.js — all socket event handlers + activeStreams
  • backend/src/controller/stream.controller.js — create/goLive/end/live/byId/recordings/search/trending
  • backend/src/route/stream.route.js — REST endpoints (note: goLive not routed)
  • backend/src/utils/ffmpeg-recorder.js — MP4 + HLS recorder
  • backend/src/middleware/validate.js — streamCreateSchema (title ≥3, description ≥10, category ≥2)
  • Frontend/src/components/pages/golive.jsx — creator dashboard
  • Frontend/src/components/pages/StreamPlayer.jsx — hls.js player
  • Frontend/src/components/profile/stream.jsx — watch page
  • Frontend/src/components/ui_layout/ui_layout_stream.jsx — /Watch layout (picks stream via ?stream=)

7. Test plan (once fixed)#

  1. npm run dev in backend/src, npm run dev in Frontend.
  2. Sign in, go to /Live, enter a title → Go Live → confirm a Stream doc appears with isLive:true.
  3. Open OBS → Settings → Stream → Server rtmp://localhost:1935/live, Key <streamKey> → Start Streaming.
  4. Confirm creator preview plays (hls.js, correct /live/{key}/index.m3u8 URL).
  5. Second browser: /Explore shows the stream; /Watch?stream=<id> plays video; chat send/recv persists (Message docs appear); viewer count increments.
  6. End stream → isLive:false, endedAt set; recording file appears under backend/recordings and is served.
  7. Analytics: a createAnalytics call 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.