1.3.3. Included samples

The Proximie SDK includes a set of sample applications that demonstrate how to integrate the Proximie SDK into your application, and use its various features. They are also a useful way to verify that your runtime or build environment is set up correctly; see Environment for details on how to set up your build environment.

1.3.3.1. Hello SDK

The hello-sdk application is a minimal example demonstrating how to integrate and use the Proximie SDK for basic video preview functionality. It is intended as a starting point for new projects and for testing SDK installation and linking.

Features:

  • Prints the Proximie SDK version to the console.

  • Accepts a --videosrc command-line option to select the video source (e.g., test for a test pattern, screen for screen capture, or a V4L2 device path).

  • Creates a video input and displays it in a preview window for a short period.

  • Writes a DOT file representing the video pipeline graph.

  • Exits automatically after a demonstration period.

Usage:

./hello-sdk --videosrc=test

Replace test with another source as needed (e.g., /dev/video0 for a webcam).

Source: samples/src/hello-sdk/hello.cpp

This app is useful for verifying your SDK build and environment, and as a template for more advanced applications.

1.3.3.2. Authentication

The auth application demonstrates how to perform authentication with the Proximie SDK using various supported methods. It does not perform any video or session operations, focusing solely on authentication logic.

Features:

  • Uses the example Authentication class to handle authentication.

  • Accepts multiple authentication options via command-line arguments (client ID, client secret, username, password, domain).

  • Attempts each authentication mode in turn until one succeeds.

  • Prints authentication status and errors to the console.

  • Checks for a refreshed access token using a refresh token.

Usage:

./auth --client-id=YOUR_ID --client-secret=YOUR_SECRET --username=YOUR_USER --password=YOUR_PASS --domain=YOUR_DOMAIN

You can supply different combinations of authentication options. The app will try each mode until successful.

Source: samples/src/auth/main.cpp

This app is useful for verifying authentication credentials and SDK connectivity, and as a reference for integrating authentication into your own applications.

1.3.3.3. Sessions

The sessions application demonstrates how to authenticate with the Proximie SDK and fetch or create a session for the authenticated user. It is focused on REST API usage and session management, without any video streaming or GStreamer dependencies.

Features:

  • Authenticates using the example Authentication class.

  • Retrieves an active session for the user, or creates a new one if none exist.

  • Demonstrates use of the PxRestApi::ProximieServices class for session management.

  • Accepts various authentication and session options via command-line arguments (such as domain and organisation).

Usage:

./sessions --client-id=YOUR_ID --client-secret=YOUR_SECRET --username=YOUR_USER --password=YOUR_PASS --domain=YOUR_DOMAIN --organisation=ORG_ID

You can supply different authentication options; the app will try each mode until successful. If no active session is found, a new session will be created in the specified organisation.

Source: samples/src/sessions/main.cpp

This app is useful for testing authentication and REST API access, and as a reference for integrating session management in your own applications.

1.3.3.4. Recording

Remotely Record Media Session

The remote recording sample demonstrates joining a media session and starting/stopping remote, in-Proximie-infrastructure recordings.

This process is explained in detail in the section Media Server Services.

Features:

  • Authenticate and join a media server session

  • Allow the user to toggle recording on/off interactively

  • Display current recording state and duration

  • Refresh authentication tokens as needed

Usage:

This sample has the same options as the Sessions sample.

Source: samples/src/recording/media-server-session/main.cpp

Locally Record Media Session

The record-local-media-session sample demonstrates how to record a media session locally using the Proximie SDK.

Features:

  • Creates a single video feed which is both recorded to a file and sent to a media session

  • Shows how to record an audio source to the file

  • Accepts an optional --videosrc command-line option to select the video source

  • Accepts an optional --audiosrc command-line option to select the audio source

Usage:

./record-local-media-session --client-id=YOUR_ID --client-secret=YOUR_SECRET --username=YOUR_USER --password=YOUR_PASS --domain=YOUR_DOMAIN

To see all available options, run the sample with --help.

Source: samples/src/recording/local-media-session/main.cpp

Locally Record Utility Feed

The file-recording sample demonstrates how to test H264 encoders by recording video from an input source directly to an MP4 file. It supports both hardware-accelerated (VAAPI) and software (x264) encoding, and is useful for benchmarking and comparing encoder performance.

Features:

  • Records video from a configurable input source to a local MP4 file

  • Supports VAAPI (hardware) and x264 (software) H264 encoders

  • Configurable video resolution, bitrate, and input format (raw YUY2 or MJPEG)

  • Custom output filename and directory options

Usage:

# Test VAAPI hardware encoder at 1080p, 4Mbps for 60 seconds
./file-recording --h264-encoder=vaapi --video-width=1920 --video-height=1080 \
                   --video-bitrate=4000 --run-time=60

# Test x264 software encoder with webcam input
./file-recording --h264-encoder=x264 --videosrc=/dev/video0 \
                   --video-bitrate=2000 --output-file=test_%02d.mp4

To see all available options, run the sample with --help.

Note that depending on your video source’s native format, you may need to specify the input format (e.g., --video-format=raw for YUY2 or --video-format=jpeg for MJPEG).

Also note that in order to use the VAAPI encoder, your system must have compatible hardware and drivers; see H.264 VAAPI Encoder for details on VAAPI support and setup.

Source: samples/src/recording/file-recording/main.cpp

Time-synchronized local recording

The synchronized-recording sample demonstrates multi-stream recording with UTC timestamp embedding for frame-accurate synchronization. Each recording file includes a UTC timestamp in its filename, enabling precise alignment of multiple feeds in post-processing. This is useful for multi-camera setups, distributed recording, and training session capture.

Features:

  • Records multiple simultaneous video feeds with audio

  • Embeds UTC timestamps in filenames for frame-accurate synchronization across feeds

  • Configurable number of feeds, recording duration, and stagger between feed starts

  • Supports multi-file recording with automatic file splitting at a configurable max duration

  • Creates per-run output subdirectories to keep recordings organized

Usage:

# Record 3 feeds for 10 seconds with 2s stagger (default)
./synchronized-recording

# Record 5 feeds for 30 seconds to a custom directory
./synchronized-recording --feeds 5 --duration 30 --output-dir /recordings

# Multi-file recording with 5-second splits (stagger auto-disabled)
./synchronized-recording --duration 15 --max-file-duration 5

To see all available options, run the sample with --help.

Source: samples/src/recording/synchronized-recording/main.cpp

1.3.3.5. V4L2 Loopback

The V4L2 loopback sample demonstrates how to capture video from an input source and output it to a V4L2 loopback device, creating a virtual camera that can be used by other applications. Note: you may need to update your version of the v4l2loopback kernel module to ensure compatibility with the SDK’s V4L2 output feed. SDK was tested with v4l2loopback version 0.15.3; older versions may not work correctly.

Features:

  • Captures video from various input sources (test pattern, screen capture, or V4L2 devices)

  • Outputs to a V4L2 loopback device (virtual camera)

  • Validates V4L2 device paths using the SDK utility functions

  • Configurable runtime duration

Prerequisites:

  • The v4l2loopback kernel module must be loaded (modprobe v4l2loopback)

  • The output device (e.g., /dev/video2) must exist and be a valid V4L2 device

  • Add loopback devices with specific settings using modprobe, for example: sudo modprobe v4l2loopback video_nr=4 max_buffers=2 exclusive_caps=1

Usage:

# Use test pattern as input, output to /dev/video2 for 60 seconds (default)
./v4l2-loopback

# Use a specific V4L2 input device as source and output to a different V4L2 loopback device
./v4l2-loopback --videosrc=/dev/video0 --v4l2-output-device=/dev/video3

# Run for a specific duration (in seconds)
./v4l2-loopback --run-time=120

Source: samples/src/virtual-camera/v4l2-loopback/main.cpp

This sample is useful for testing V4L2 output functionality and as a reference for creating virtual camera applications.

1.3.3.6. Stages

The stages sample demonstrates how to use the Proximie SDK to add different stages to a feed. It shows the creation and application of video and audio stages to a utility feed.

Features:

  • Demonstrates creation and application of multiple audio and video stages to a feed.

Usage:

./stages

Run the sample with --help to see available options for configuring the stages.

Source: samples/src/stages/stages.cpp

1.3.3.7. Reusable Inputs

The reusable-inputs sample demonstrates how to create reusable input sources using the Proximie SDK. It shows how to set up a video input sources that can be shared across multiple feeds.

Features:

  • Creates reusable video input sources.

  • Demonstrates sharing of input sources across multiple feeds.

  • Uses video stages to independently manipulate each feed’s video.

  • Demonstrates switching between input sources.

Usage:

To simply demonstrate the use of a test video source for two feeds, run:

./reusable-inputs

To rotate one of the feeds by 90 degrees, run:

./reusable-inputs --output-2-video-rotate

To see all available options, run the sample with --help.

1.3.3.8. Complete

This sample brings together many of the available functions in the SDK into one place. As such, it can be harder to follow and break down into individual components.

Features used include:

  • Logging

  • Adaptive streaming

  • Preview

  • Starting feeds

  • Writing DOT files

  • recording

  • Authentication

  • Sessions

  • Getting and creating media server session

  • Feed notifications

  • Rotate and crop

  • Audio

1.3.3.9. Peer-to-peer samples

Peer Simplex

The peer-simplex sample illustrates a one-way (simplex) peer-to-peer connection using the Proximie SDK. It sets up a session where media flows in a single direction, without the need for a coordination server. This sample covers session initiation, media stream setup, and basic peer event handling, providing a foundation for applications that require one-way peer-to-peer media transmission.

Features:

  • Establishes a simplex (one-way) peer connection.

  • Demonstrates session setup and media stream initialization.

  • Useful for LAN or non-internet scenarios.

  • Independent streaming and recording pipelines

Usage:

To stream from Peer A to Peer B, run the following command on Peer A:

./peer-simplex --peer-role=local

Then, on Peer B, run:

./peer-simplex --peer-role=remote

To see all available options, run the sample with --help.

Source: samples/src/peer/simplex/main.cpp

Peer Duplex

The peer-duplex sample demonstrates a two-way (duplex) peer connection with the Proximie SDK. It establishes a session where media can be sent and received between peers. The sample covers session negotiation and bidirectional media streaming, providing a template for applications that require full two-way collaboration.

Features:

  • Establishes a duplex (two-way) peer connection.

  • Demonstrates bidirectional media streaming and session negotiation.

  • Useful for LAN or non-internet scenarios.

  • Independent streaming and recording pipelines

  • Audio mixing

Usage:

To run the duplex peer sample, simply execute:

./peer-duplex

The sample will create a duplex connection with itself (loopback) for demonstration purposes.

To test between two separate peers, run the command on two different machines, and pass the other peer’s IP address using the --remote option.

To see all available options, run the sample with --help.

Source: samples/src/peer/duplex/main.cpp

1.3.3.10. Audio mixing

The audio-mixing application is a minimal example demonstrating the audio mixer feed.

Features:

  • Mixing 2 different audio signals. The second source is toggled every second.

Usage:

./audio-mixing

Source: samples/src/audio-mixing/main.cpp