encoded_video_ingest

Author: stephen-derosa

CMakeLists.txt

@@ -93,3 +93,8 @@ add_subdirectory(simple_joystick_sender)
 add_subdirectory(simple_joystick_receiver)
 add_subdirectory(ping_pong_ping)
 add_subdirectory(ping_pong_pong)
+<<<<<<< Updated upstream
+=======
+add_subdirectory(user_timestamped_video)
+add_subdirectory(encoded-video-ingest)
+>>>>>>> Stashed changes

encoded-video-ingest/CMakeLists.txt

@@ -0,0 +1,34 @@
+# Copyright 2026 LiveKit, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+add_executable(EncodedVideoIngestProducer
+  producer.cpp
+)
+
+target_include_directories(EncodedVideoIngestProducer PRIVATE ${CMAKE_CURRENT_SOURCE_DIR})
+target_link_libraries(EncodedVideoIngestProducer PRIVATE ${LIVEKIT_CORE_TARGET})
+
+livekit_copy_windows_runtime_dlls(EncodedVideoIngestProducer)
+
+add_executable(EncodedVideoIngestConsumer
+  consumer.cpp
+)
+
+target_include_directories(EncodedVideoIngestConsumer PRIVATE ${CMAKE_CURRENT_SOURCE_DIR})
+target_link_libraries(EncodedVideoIngestConsumer PRIVATE ${LIVEKIT_CORE_TARGET})
+if(WIN32)
+  target_link_libraries(EncodedVideoIngestConsumer PRIVATE ws2_32)
+endif()
+
+livekit_copy_windows_runtime_dlls(EncodedVideoIngestConsumer)

encoded-video-ingest/README.md

@@ -0,0 +1,150 @@
+# encoded-video-ingest
+
+End-to-end demo of encoded video ingest in the LiveKit C++ SDK. The
+producer uses `livekit::EncodedTcpIngest`, the high-level SDK helper that owns
+the TCP reconnect loop, H.26x access-unit splitting, keyframe feedback, stats,
+and track publishing.
+
+## Prerequisites
+
+- A LiveKit server, such as `livekit-server --dev`.
+- GStreamer 1.22+ with `good`, `bad`, `ugly`, and `libav` plugins.
+- Two LiveKit tokens for the same room:
+
+```bash
+export LIVEKIT_URL=ws://localhost:7880
+export PRODUCER_TOKEN="$(lk token create -r encoded-video-demo -i encoded-sender --join --publish)"
+export CONSUMER_TOKEN="$(lk token create -r encoded-video-demo -i encoded-receiver --join --subscribe)"
+```
+
+# Setup Validation
+
+**Before bringing LiveKit into the picture**, confirm your camera encode path
+and a basic H.264 decode preview work in pure GStreamer. The **send** and
+**receive** commands below use the **same UDP port (5005)** on purpose:
+`udpsink` sends RTP to `127.0.0.1:5005` and `udpsrc` binds `port=5005` for a
+quick local check.
+
+That is only for this camera-validation hop. In the full LiveKit demo below,
+**port 5005** is reserved for **TCP** from the camera pipeline into the
+producer, and **port 5006** is where the consumer serves **decoded I420** to a
+separate GStreamer visualizer.
+
+### Send - camera to RTP/UDP 5005
+
+macOS (`avfvideosrc`). Linux: replace the source with
+`v4l2src device=/dev/video0`. Windows: `mfvideosrc device-index=0`. If the
+camera cannot produce 640x480 natively, add `videoscale ! videorate !` before
+`x264enc` and relax the first caps filter as needed.
+
+```bash
+gst-launch-1.0 -v \
+  avfvideosrc ! \
+  video/x-raw,width=640,height=480,framerate=30/1 ! \
+  videoconvert ! \
+  x264enc tune=zerolatency bitrate=1000 speed-preset=ultrafast key-int-max=30 ! \
+  video/x-h264,profile=baseline ! \
+  rtph264pay pt=96 config-interval=1 ! \
+  udpsink host=127.0.0.1 port=5005
+```
+
+### Receive - RTP/UDP 5005 to display
+
+```bash
+gst-launch-1.0 -v \
+  udpsrc port=5005 caps="application/x-rtp,media=video,encoding-name=H264,payload=96" ! \
+  rtph264depay ! \
+  avdec_h264 ! \
+  videoconvert ! \
+  autovideosink
+```
+
+On macOS, if `autovideosink` hangs at `PREROLLING`, replace it with
+`osxvideosink`.
+
+This path validates camera, encoder, and decoder. It is **not** the same wire
+format as the ingest path: the demo ingest uses **TCP** and **Annex-B** with
+**AUD-delimited** access units. For that path use `x265enc` with AUD enabled,
+`h265parse`, and `tcpserversink` as shown below.
+
+### Debugging a blank / green receive window
+
+Before blaming the network, collapse encode to decode into a single local
+pipeline. A green square here means the encoder is being fed buffers it cannot
+consume, such as the wrong pixel format, GL memory, or no frames at all:
+
+```bash
+gst-launch-1.0 -v \
+    avfvideosrc device-index=0 ! \
+    video/x-raw,width=640,height=480,format=NV12,framerate=30/1 ! \
+    videoconvert ! \
+    x264enc tune=zerolatency speed-preset=ultrafast bitrate=1000 key-int-max=60 aud=true ! \
+    h264parse config-interval=1 ! avdec_h264 ! videoconvert ! autovideosink sync=false
+```
+
+Common causes of a green or all-black preview:
+
+- **macOS camera permission.** Grant your terminal app Camera access in
+  *System Settings -> Privacy & Security -> Camera* and relaunch it.
+- **`memory:GLMemory` on the source pad.** Pinning `format=NV12` on the first
+  caps filter forces a CPU buffer.
+- **Caps pinned to a mode the camera cannot produce.** Run
+  `gst-device-monitor-1.0 Video/Source` and pick a listed `video/x-raw` mode.
+
+## 1. Encode a webcam to TCP port 5005 using H.265
+
+`tcpserversink` listens on **TCP** port **5005**. Stop any other TCP listener
+on that port before starting this command.
+
+```bash
+gst-launch-1.0 -v \
+    avfvideosrc device-index=0 ! \
+    video/x-raw,width=640,height=480,format=NV12,framerate=30/1 ! \
+    videoconvert ! \
+    x265enc tune=zerolatency speed-preset=ultrafast bitrate=1000 key-int-max=60 \
+        option-string="aud=1:repeat-headers=1" ! \
+    h265parse config-interval=1 ! \
+    video/x-h265,stream-format=byte-stream,alignment=au ! \
+    tcpserversink host=0.0.0.0 port=5005
+```
+
+Linux: replace `avfvideosrc device-index=0` with
+`v4l2src device=/dev/video0`. Windows: use `mfvideosrc device-index=0`.
+
+## 2. Run the producer
+
+```bash
+LIVEKIT_URL=ws://localhost:7880 LIVEKIT_TOKEN="$PRODUCER_TOKEN" \
+  ./build/encoded-video-ingest/EncodedVideoIngestProducer \
+    --tcp-host 127.0.0.1 --tcp-port 5005 \
+    --width 640 --height 480 \
+    --codec h265
+```
+
+The producer starts `EncodedTcpIngest`, publishes a camera track named
+`encoded-video`, and logs stats every two seconds.
+
+## 3. Run the consumer
+
+```bash
+LIVEKIT_URL=ws://localhost:7880 LIVEKIT_TOKEN="$CONSUMER_TOKEN" \
+  ./build/encoded-video-ingest/EncodedVideoIngestConsumer \
+    --tcp-port 5006 \
+    --from encoded-sender
+```
+
+The consumer subscribes to `encoded-sender` and serves decoded I420 frames on
+TCP port 5006.
+
+## 4. View the consumer output
+
+```bash
+gst-launch-1.0 -v \
+    tcpclientsrc host=127.0.0.1 port=5006 ! \
+    rawvideoparse width=640 height=480 format=i420 framerate=30/1 ! \
+    videoconvert ! autovideosink sync=false
+```
+
+`rawvideoparse` needs the exact width and height that the producer declared.
+The consumer output is raw I420, not H.265, so do not pipe port 5006 through
+`h265parse`.