1.3.3. Running samples

Once you have set up your environment (see Environment) and obtained the sample applications (see Obtaining the sample applications), you can run the samples to see the SDK in action and validate your 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 configurable demonstration period (--run-time, default 10 seconds).

• Supports --video-output to select between a window display (window, default), UDP/RTP output (udp), or no output (none).

• Accepts --udp-port to set the UDP port when using --video-output=udp (default: 5004).

Usage:

C++Python

To run the C++ version of the sample, execute:

./hello-sdk --videosrc=test

# Run for 30 seconds with no display
./hello-sdk --videosrc=test --video-output=none --run-time=30

# Output encoded video over UDP/RTP
./hello-sdk --videosrc=test --video-output=udp --udp-port=5004

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

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:

C++Python

./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.

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:

C++Python

./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.

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:

C++Python

This sample has the same options as the Sessions sample.

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:

C++Python

./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.

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:

C++Python

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

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:

C++Python

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

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:

C++Python

# 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

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

1.3.3.6. Shared Memory

The shared memory sample demonstrates how to stream raw video between processes using the SDK’s shared memory feed components. These components enable efficient, zero-copy video transfer between processes on the same machine: VideoOutputFeedSharedMemory (backed by GStreamer’s shmsink) publishes raw video to a shared memory area identified by a control socket, and VideoInputFeedSharedMemory (backed by shmsrc) reads it back. Run two instances using the same socket path: one as a writer and one as a reader.

Features:

• Publishes raw video from any input source (test pattern, screen capture, file or device) into a shared memory area using VideoOutputFeedSharedMemory.

• Reads raw video from a shared memory area using VideoInputFeedSharedMemory and displays it.

• Demonstrates pairing the two endpoints over a common socket path.

• Configurable socket path, buffer size, resolution and frame rate via command-line options.

Warning

Shared memory transfers raw bytes with no caps negotiation, so the reader’s dimensions (resolution, frame rate and pixel format) must exactly match the writer’s published frame or the bytes are silently misinterpreted. See the format-matching notes for the resolution-changing stages to account for and the adaptive-streaming caveat.

Usage:

C++Python

# Terminal 1: write the test pattern into shared memory
./shared-memory --mode=writer --socket-path=/tmp/px-shm-video

# Terminal 2: read the shared memory and display it
./shared-memory --mode=reader --socket-path=/tmp/px-shm-video

# Use a webcam as input and specify resolution
./shared-memory --mode=writer --videosrc=/dev/video0 --width=1920 --height=1080

Run the sample with --help to see all available options.

1.3.3.7. 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.

• Accepts --audiosrc (testsignal or mic) and --audiosink (wavescope, live, or none) options.

• Supports --video-output to select between a window display (window, default), UDP/RTP output (udp), or no output (none).

• Accepts --udp-port to set the UDP port when using --video-output=udp (default: 5004).

Usage:

C++Python

./stages

# Run headless with no audio or video output
./stages --audiosink=none --video-output=none

# Output video over UDP/RTP
./stages --video-output=udp --udp-port=5004

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

1.3.3.8. Adaptive streaming (experimental)

The adaptive-streaming sample demonstrates how to implement adaptive streaming using the forthcoming (currently experimental) adaptive streaming feed components in the Proximie SDK. It shows how to set up an adaptive streaming feed for a media server session, configure quality levels, and handle quality monitoring and manual overrides.

Features:

• Command line options to enable adaptive quality for frame rate, resolution and bit rate.

• Joins a media server session, and creates an adaptive streaming enabled outgoing feed

• Creates a local and monitor window, showing the video before and after quality adjustments respectively

• Interactively allows the user to set the quality level of the feed to see how quality levels can dynamically adjust the outgoing video

• Optionally enables a quality monitor which will automatically adjust quality levels based on WebRTC stats returned by the outgoing feed.

Usage:

This sample uses a media server session to demonstrate its functionality; see the Sessions sample for details about authentication.

C++Python

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

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

1.3.3.9. 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.

• Configurable demo duration via --run-time (default: 10 seconds).

• Supports --video-output to select between a window display (window, default), UDP/RTP output (udp), or no output (none) for the primary output feed.

• Accepts --udp-port to set the UDP port when using --video-output=udp (default: 5004).

Usage:

C++Python

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 run headless with UDP video output for 5 seconds:

./reusable-inputs --video-output=udp --run-time=5

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

1.3.3.10. 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.11. 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

• Monitor output support for viewing encoded video after encoder (window or UDP)

• --audiosink accepts live, wavescope, or none to control audio output.

Usage:

C++Python

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.

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

• Supports --video-output to select between a window display (window, default), UDP/RTP output (udp), or no output (none) for incoming video.

• Accepts --udp-port to set the UDP port when using --video-output=udp (default: 5004).

• --audiosink accepts live, wavescope, or none to control audio output.

Usage:

C++Python

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.

1.3.3.12. 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:

C++Python

./audio-mixing

1.3.3.13. Wayland desktop capture

The wayland-capture sample demonstrates how to capture the desktop on Wayland using the Proximie SDK. It negotiates screen sharing permission via the XDG Desktop Portal, obtains a PipeWire video stream of the user’s chosen monitor, and displays it in a local preview window using the SDK’s utility feed.

On Wayland, applications cannot directly access the screen contents of other windows (unlike X11). Instead, the XDG Desktop Portal — a standardised D-Bus service — mediates screen capture: the user is shown a dialog to choose which monitor or window to share, and the portal creates a PipeWire media stream containing the screen contents. This sample uses VideoInputFeedPipewire to consume the PipeWire stream, VideoOutputFeedAuto to render the video, and UtilityVideoLocalFeed to connect them.

Prerequisites:

• A Wayland compositor with XDG Desktop Portal support (GNOME, KDE Plasma, wlroots-based, etc.)

• xdg-desktop-portal and a compositor-specific backend installed (e.g. xdg-desktop-portal-gnome)

• PipeWire running (standard on modern Fedora, Ubuntu 22.04+, etc.)

• GStreamer with the PipeWire plugin (gstreamer1.0-pipewire)

• The sample must be launched from within an active, graphical Wayland desktop session (for example, from a terminal opened inside that desktop session)

Warning

This sample requires a real graphical desktop session and is not supported headless or in Docker.

The XDG Desktop Portal presents an interactive screen-picker dialog that only appears within a running graphical desktop session:

• Headless / non-graphical terminals (e.g. an SSH session with no desktop, or an automated/agent terminal): the portal D-Bus session is created successfully, but the picker dialog never becomes visible. The sample then waits for the portal’s Response signal indefinitely — it will appear to hang after printing Portal session created: (followed by the session handle) with no error and no picker, until it is interrupted with Ctrl+C.

• Docker containers: portal negotiation typically fails outright, because the container’s user ID does not match the desktop session owner that the portal authorises against.

Run this sample from a terminal opened inside a graphical Wayland desktop session on the host, not from a headless shell or a container.

Features:

• Performs the full XDG Desktop Portal negotiation (CreateSession → SelectSources → Start → OpenPipeWireRemote) using GDBus

• Configures a VideoInputFeedPipewire with the portal-provided PipeWire file descriptor and stream node ID

• Displays the captured desktop video in a local preview window via VideoOutputFeedAuto

• Runs until the user presses Ctrl+C

Usage:

C++Python

./wayland-capture

A system dialog will appear asking which monitor to share. After selecting a monitor, a window will open showing the captured desktop content in real time.

This sample is useful as a starting point for Wayland-based screen capture applications, and as a reference for integrating XDG Desktop Portal negotiation with the Proximie SDK’s PipeWire video input.

1.3.3.14. Annotation Reception

The annotation-reception application demonstrates subscribing to live annotation (telestration) events and fetching annotation history via REST. It shows how to handle duplicate events between live and historical data using seqNum-based deduplication.

Features:

• Subscribes to annotation events for all feeds in a connected session

• Registers an experimental().onAnnotationReceived callback for live event delivery

• Fetches persisted annotation history via experimental().fetchAnnotationHistory

• Deduplicates overlapping live and historical events using (streamId, seqNum) pairs

• Optionally publishes a test-pattern video feed (--publish-video) for self-testing

Usage:

C++Python

./annotation-reception --domain=<domain> --client-id=<id> --username=<user> --password=<pass> \
    --organisation=<org> --run-time=<seconds> --publish-video

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