Download Demo Source Code

2026-09-18

Note

This article describes how to quickly run the demo source code and experience the basic audio/video stream recording feature.

Prerequisites

You have created a project in the ZEGOCLOUD Console and obtained a valid AppID. For details, see "Project Information" in Console - Project Management.
The development and running environments must meet the following requirements:
- Operating system and architecture: Linux operating system with the x86_64 architecture
- C runtime library: glibc 2.18 or above
- C++ compiler: GCC / G++ 4.8.5 or above, with C++11 enabled
- Build tools: CMake 3.21.2 or above, Make
- Command-line tools: Bash, curl, unzip
- Underlying dependency libraries: libasound(ALSA), libv4l2(v4l utils)
- Operating system and architecture: Linux operating system with the x86_64 architecture
- C runtime library: glibc 2.18 or above
- Java development tools: 64-bit JDK 8 or above, including the java, javac, and jar commands
- Command-line tools: Bash, curl, unzip
- Underlying dependency libraries: libasound(ALSA), libv4l2(v4l utils)
Note
- The SDK depends on libasound (ALSA) and libv4l2 (v4l utils).
- CentOS (RHEL/Fedora): install them by running the yum install alsa-lib-devel libv4l-devel command.
- Ubuntu (Debian/Deepin): install them by running the apt install libasound2-dev libv4l-dev command.
- For other platforms and systems, install them by yourself.
- If cross-compilation is required, see the documents How to cross-compile the Linux alsa-lib dependency library? and How to cross-compile the Linux v4l-utils dependency library?, and make sure the libasound and libv4l2 dependency libraries are installed on the target machine.
You can run the following commands to check whether the server's running environment meets the requirements:
```
uname -m                         # Should output x86_64
getconf GNU_LIBC_VERSION          # Should be glibc 2.18 or above
g++ --version
cmake --version
make --version
```
```
uname -m                         # Should output x86_64
getconf GNU_LIBC_VERSION          # Should be glibc 2.18 or above
g++ --version
cmake --version
make --version
```
```
uname -m                         # Should output x86_64
getconf GNU_LIBC_VERSION          # Should be glibc 2.18 or above
java -version
javac -version
```
```
uname -m                         # Should output x86_64
getconf GNU_LIBC_VERSION          # Should be glibc 2.18 or above
java -version
javac -version
```

Download the Demo Source Code

Demo Source Code

Download locally Linux - C++

Directory structure of the demo source code

.
├──docs
└──cpp
    ├── CMakeLists.txt
    ├── README.md
    ├── build.sh
    ├── demo_config.yaml
    ├── run.sh
    ├── sdk
    │   ├── Document
    │   ├── Library
    │   └── VERSION.txt
    └── src
        ├── CommandLine.h
        ├── LiveRoomRecorder.cpp
        ├── LiveRoomRecorder.h
        ├── RecorderConfig.h
        ├── Yaml.cpp
        ├── Yaml.hpp
        └── main.cpp

.
├──docs
└──cpp
    ├── CMakeLists.txt
    ├── README.md
    ├── build.sh
    ├── demo_config.yaml
    ├── run.sh
    ├── sdk
    │   ├── Document
    │   ├── Library
    │   └── VERSION.txt
    └── src
        ├── CommandLine.h
        ├── LiveRoomRecorder.cpp
        ├── LiveRoomRecorder.h
        ├── RecorderConfig.h
        ├── Yaml.cpp
        ├── Yaml.hpp
        └── main.cpp

Run the Demo Source Code

Extract the package and enter the demo source code directory.

Build the project.

bash build.sh

bash build.sh

The build output is build/playrecorderdemo.

Modify the project configuration file.

# Copy the configuration file template
cp demo_config.yaml local_config.yaml

# Copy the configuration file template
cp demo_config.yaml local_config.yaml

For the first run, you can keep mode: 1, room_mode: 0, muxer_out_type: 1, suffix: "mp4", and single.fragment: 0 in the template. Then fill in the following main configurations:

appid: replace it with the AppID obtained from the ZEGOCLOUD Console.
use_token: whether to use Token authentication. 1 means use, 0 means not use. If Token authentication is not used (0), fill in the app_sign field; if Token authentication is used (1), fill in the token_list field and keep app_sign: "none".
room_list: replace it with the ID of the room that is publishing streams, and keep the string quotes.
user_id and user_name: set the identity of the recording user.
log_path: set a writable absolute directory, for example /home/your-user/recorder-output. The actual path must exist or allow being created.

Note

Keep the local configuration containing AppSign or Token safe, and do not commit it to the code repository.

Common configuration fields in local_config.yaml

Field	Configuration Requirement
`appid`	App ID, a positive integer; the publishing client and the recording client use the same app
`use_token`	`1` to use Token, `0` to use AppSign
`app_sign`	When using AppSign authentication, fill in 64 hexadecimal characters; when using Token authentication, keep `none`
`token_list`	When using Token authentication, keep the same order and count as room_list; use the Token issued by the server for the recording user
`room_list`	A list of room ID strings; also quote numeric IDs to avoid losing leading zeros
`user_id` / `user_name`	The identity of the recording user, which must not duplicate any other user in the room; the identity in the Token must match user_id
`room_mode`	`0` single room, only the first element of room_list is used; `1` multiple rooms
`mode`	`1` single stream; `2` mixed stream; `3` record both single stream and mixed stream
`log_path`	Root directory for logs and the demo's recording files; an absolute path is recommended; the directory for this session is printed at startup
`persistence_path`	Path for the SDK's persisted configuration; the demo still explicitly outputs recordings and screenshots to the current session directory
`suffix`	Use `mp4` for initial verification; `mp3` is available for audio recording
`muxer_out_type`	Use `1` to verify file recording; `2` means callback data only, and this demo does not implement persisting callback data
`single.fragment`	Single-stream fragment interval. Set it to `0` for initial MP4 verification, and check the complete file after stopping
`mix.fragment`	Mixed-stream fragment interval. Set it to `0` for initial MP4 verification
`mix.output_width` / `mix.output_height`	Width and height of the mixed-stream canvas, for example 1280 × 720
`mix.output_fps` / `mix.output_bitrate`	Frame rate and bitrate of the mixed-stream video, in fps and bps respectively

Run the demo.

bash run.sh start --config ./local_config.yaml

bash run.sh start --config ./local_config.yaml

Note

run.sh keeps the caller's current working directory, so the configuration file and relative paths in the configuration are all resolved against the directory where the command is executed. It is recommended to always use absolute paths when deploying the service.
After the demo is initialized successfully, it automatically logs in to the room and records the discovered streams. There is no need to manually enter record start to start recording.

After recording starts, you can check the recording progress from the terminal output:

The initialization callback error code is 0.
The login callback error code is 0, and the room ID matches the configuration.
The expected stream ID appears in the stream update callback.
The recording start callback provides the file path. For single-stream recording, you can use record status to help observe the duration and size; for mixed-stream recording, check the recording callbacks and the output files after stopping.
After recording for a while, enter stop, then check the recording end callback and the files under the log_path output; then run exit.

If FFmpeg is installed, you can check the output files:

ffprobe -v error -show_entries format=duration,size \
  -show_entries stream=codec_type,codec_name,width,height \
  -of json /absolute/path/to/recording.mp4

ffprobe -v error -show_entries format=duration,size \
  -show_entries stream=codec_type,codec_name,width,height \
  -of json /absolute/path/to/recording.mp4

After single-stream recording succeeds, run stop first, change mode to 2 and mix.fragment to 0 in the configuration, and then restart. Check the layout and sound of the mixed-stream file, and try mix pause and mix resume. When mode: 3 is used, both single-stream and mixed-stream files are generated, and both types of files need to be checked.

run.sh command-line parameters

Command	Purpose
`start --config ./demo_config.yaml`	Load the configuration, initialize, log in to the room in the configuration, and automatically record newly added streams. If a path contains spaces, use single or double quotes.
`stop`	Stop recording, exit the room, and release the SDK; you can start again afterwards
`room login --room-id room1`	Log in to the specified room; for multi-room operations, room_mode must be configured before initialization
`room logout --room-id room1`	Exit the specified room
`room set-token --room-id room1 --token-file ./room1.token`	Set or update the Token for a room; the file is a single-line UTF-8 text file, with or without a trailing newline
`record start --room-id room1 --stream-id stream1`	Manually start recording the specified single stream
`record stop --room-id room1 --stream-id stream1`	Manually stop recording the specified single stream
`record status`	Query the recording duration, size, and path
`mix pause` / `mix resume`	Pause or resume the ongoing mixed-stream recording
`stream sei`	Query the latest SEI time of the discovered streams
`snapshot --stream-id stream1`	Take a screenshot of a single stream
`snapshot --mix`	Take a screenshot of the mixed stream
`help` / `start --help`	View command help
`exit`	Stop recording and exit the program

Note

stream-id should be obtained from the stream update callback, and cannot be replaced with the room ID. Streams that are automatically recorded do not need record start again.
End of input (EOF) automatically stops the program, so do not start continuous recording with echo 'start ...' | ....
After running start via the startup parameter, keep the terminal input open, and enter exit after recording is complete to stop recording and exit the program.

FAQ

Initialization is rejected or the callback reports an error

Check the App ID, authentication configuration, and SDK logs; the API returning true only means the request was accepted

Check the app, room, and user IDs; whether the Token has expired, and whether it was issued to this recording user

Make sure the publishing client uses the same app and room and has started publishing; the room ID and stream ID are different concepts

Streams exist but no files are generated

Check the recording start/end callbacks, resource mode, output directory permissions, and disk space; muxer_out_type should be 1

The MP4 cannot be played temporarily

Stop normally first and wait until the file is finalized before checking; force-killing the process may leave an unfinished file

The mixed stream has no video or the layout is incorrect

Check the canvas width/height, the number of input streams, and the rectangle coordinates; the x-coordinate must not exceed the width, and the y-coordinate must not exceed the height

A message indicates the SDK is not initialized

Wait for the initialization result before operating; if initialization fails, correct the configuration and start again