You want to stream a low latency h.264-video from a camera? Use this code! Thanks to its modular structure, the USB camera frame grabber can be easily replaced by code for other cameras such as Ximea industrial cameras, as shown in the second example. Video parameters such as resolution and frame rate can be set in the config file.
This project is intended to kickstart C++ projects that require low latency video streaming and to provide a sample implementation of the x264 video encoder in C++.
This code is continuously built on the latest Ubuntu. The project relies on the multi-platform libraries OpenCV, ffmpeg, and x264. Thus, the following Ubuntu-specific instructions are similar on other platforms such as OS X or Windows. The following software is required for both code samples.
- Install CMake, build-essential, FFmpeg, x264, and OpenCV:
sudo apt install -y build-essential cmake ffmpeg libx264-dev x264 libopencv-dev libva-dev libsdl2-dev
For compiling the Ximea sample (disabled by default), the following additional setup steps need to be performed:
- Install the Camera driver and SDK. Installation is described on the linked webpage. During installation, do not use the -pcie argument.
- After installation, increase the USB buffer size in Linux (add 'echo 0 > /sys/module/usbcore/parameters/usbfs_memory_mb' to /etc/rc.local) and allow the application to run in realtime.
Clone this repository into a folder of your choice
git clone https://github.com/cbachhuber/CppVideoStreamer # clone the repository
cd CppVideoStreamer # change into the cloned directory
mkdir build && cd build # create a build folder, and change into it
cmake .. # configure the build files
make # build the binariesPer default, the project only builds the USB camera sample, not requiring any Ximea software. If you would like to build the Ximea sample, add the flag -DBUILD_XIMEA=ON to the cmake command, such that it reads cmake -DBUILD_XIMEA=ON ...
Before starting the program, adjust the settings in config.yaml to your requirements. You can then start the programs from the build folder using
./usbCamStreamerThis will run the streamer program, which defaults to read the config file in ../src/config.yaml relative to the executable. Alternatively, you can define the location of the config file as command line argument of the application, e.g.
./usbCamStreamer ../src/config.yamlhas the same effect as calling with no parameter. The analog procedure can be performed for the Ximea sample, for which the executable is called ximeaStreamer. At startup, both programs wait for a client to connect to the opened TCP socket, which is per default on localhost, port 5001. If you do not yet have a video sink, you can run
ffplay -probesize 32 -sync ext tcp://127.0.0.1:5001in an additional terminal to connect to the open port and start playing back the streamed video. The streamer will now proceed to open the camera defined in config.yaml and will finally stream the camera feed to the ffplay player instance. Note that ffplay, even with the above low latency settings, adds considerable delay. An alternative player is listed under Alternative video player.
You can gracefully quit both programs by pressing q while in the ffplay video player. This will quit the player, and inform the streamer that the TCP partner has shut down, which causes the streamer to close the camera and terminate.
Under src/receiver, a stub of a video player is provided. It is written in C++ and uses SDL2 to display the video. Barebone interaction to control latency and to quit the program has been implemented. Set variable video_url to the URL of the video stream, and configure and compile the program using commands from building. Then, run the program when the streamer is already running, from your build directory with
./src/receiver/video_playerThis repository is licensed under GPL-3.0. We'd prefer to have a more permissive license, however, we're depending on x264 which itself has a GPL license. That forces us to use GPL as well.