5.2.1. Release notes for v0.13

Feature: “Privacy mode” video stage

VideoStagePrivacy is a new video feed stage that allows the application to switch the video feed to a “privacy mode” (which is a black video feed) at runtime. The privacy feature is an example of a new capability to send requests to feeds at runtime using the feedRequest() function. In the future, the SDK will support more requests, but for now the privacy feature demonstrates the concept.

First, the application adds a VideoStagePrivacy as a stage (stages are outlined in the Feed Stages section):

using namespace PxMedia;

VideoInputFeedV4Linux2 video;
video.videoCapabilities().frameRate(30);  // etc...

VideoStagePrivacy privacy;
video.videoStages().sequence({privacy});

Then the application can call feedRequest() on the feed to a request:

// A request object to set the privacy on (true)
VideoStagePrivacy::RequestPrivacy privacyOn(true);

// Send the request to the feed
auto handled = feed->feedRequest(privacyOn);
if (!handled) {
    auto error = handled.error();
    // Handle the error...
}

Requests return an outcome value, which will contain an error if the request was not handled. This may happen if the feed was not yet playing, or if the feed was not set up to handle the request (e.g. if the application omitted to add the stage which handles that type of request).

For more information on feed requests, see the Feed Requests section.

Known issues with the privacy mode feature:

• When privacy mode is used with a AVOutputFeedFile, switching the privacy mode will cause a new recording file to be started.

• Additionally, the AVOutputFeedFile reports an error “decreasing DTS value” when switching privacy mode, but this does not cause any behavioural issues.

• There is an interaction between VideoStageRotateFlip and privacy, which causes the feed to error when used together. Please do not use these two features together with the current release.

All of the above issues will be addressed in a future release.

Updated demo features

The demo application can now demonstrate:

1. The existing SDK recording functionality using AVOutputFeedFile.

2. The new privacy mode feature using VideoStagePrivacy.

These are enabled using the command line options --demo-recording and --demo-privacy. Set these options using the form --option=on to enable the feature (these can also be set using environment variables, PXSDK_DEMO_RECORDING and PXSDK_DEMO_PRIVACY).

Recording demonstration:

• Instead of showing the webcam preview on startup, the demo records it to a file in the current directory.

Privacy mode demonstration:

• Privacy mode causes the video feed to switch to black.

• The webcam preview toggles privacy on then off again, before processing to authentication.

• The outgoing video feed also toggles privacy at intervals while the demo is running.

Feature: New video feed stage: VideoStageGaussianBlur (experimental)

VideoStageGaussianBlur allows the application to apply a blur filter as a video feed stage. Blur level is set with the sigma() property, which is a floating point value where zero is no blur, positive values increasing blur, and negative values giving a sharpening effect. However, it’s important to note that the current implementation is a simple CPU-based effect, so not suitable for high resolutions and/or frame rates. For this reason, be warned that VideoStageGaussianBlur is an experimental feature.

Feature: Maximum video feeds per session increased from 4 to 8

The first client to join a Proximie session sets several session parameters, including the maximum number of video feeds. A Proximie-SDK-based client will now set this value to 8, rather than 4. Note that if a web client is first to join, it will still set the maximum to 4.

Documentation: Peer duplex streaming demonstration

Example code has been added in the form of a new demo application, demonstrating bidirectional/duplex streaming between two peers. It can be found in samples/demo/demo-duplex-peer-app.cpp.

Documentation: Local video output configuration

There is now a Video Outputs section of the SDK documentation that describes how to configure local video outputs. This demonstrates how to configure both outgoing and incoming videos feeds in both peer and media server session contexts. It includes examples of local GUI, RTP/UDP, and disabled video outputs. VideoOutputFeedFake documentation has also been corrected.

Documentation: Peer demo app additional parameters

The peer demo app has been updated to demonstrate additional parameters for configuring the local video input and output. This includes:

1. Setting the local video source resolution

2. Setting the local video source frame rate

3. Setting local RTP/UDP output stream bitrates

Peer demo app arguments and documentation have been updated to reflect these changes.

The media server demo app has also been updated to include the setting of bitrate for RTP/UDP output of received remote video streams.

Fix: SDK shutdown improvements

Previous versions of the SDK would sometimes cause a segfault when shutting down. Changes to the Proximie Context and underlying SDK-internal contexts have been made to ensure that contexts are not destroyed early, and to prevent thread-waiting deadlocks during shutdown.

Feature: New video feed stages

This release adds some new “video stages” that can be applied to video feeds.

VideoStageResize allows the application to set a different resolution size for the video feed. This can be useful since physical devices support a limited number of resolutions, but application may want to alter these for various purposes.

VideoStageFrameRate allows the application to set a different frame rate for the video feed. Again, this may be useful to choose a frame rate that may not be supported by the input source.

VideoStageTextOverlay allows a feed to have text overlaid over the video. There are various formatting options for the text, e.g.:

using namespace PxMedia;

VideoInputFeedV4Linux2 video;
video.videoCapabilities().frameRate(30);  // etc...

VideoStageTextOverlay textOverlay;
textOverlay.text("PREVIEW\n[Local webcam]")
    .fontDescription("Sans bold")
    .textColor({1.0, 1.0, 0.0})  // R,G,B values [0.0..1.0] so yellow text
    .horizontalAlignment(VideoStageTextOverlay::HorizontalAlignment::Left)
    .verticalAlignment(VideoStageTextOverlay::VerticalAlignment::Bottom);
video.videoStages().sequence({textOverlay});

UtilityVideoLocalFeed::FeedProperties props{"webcam-preview"};
VideoOutputFeedAuto                   output;
auto feedCreated = UtilityVideoLocalFeed::create(context, props, video, output);

See the VideoStageTextOverlay documentation for more details on the various options.

The existing VideoStageRotateCrop class has been deprecated, and the SDK now separates the functionality into VideoStageRotateFlip and VideoStageCrop.

For more information on video stages, see the Feed Stages section.

Feature: Extra local recording features for AVOutputFeedFile

The AVOutputFeedFile class now supports some additional features:

1. The onFeedFileFinished() function allows applications to register a callback that will be called when a recording files has finished (e.g. when splitting on size or time).

2. The fileOutputLocationHandler() function allows applications to set the output file location and file name for each recording file.

3. You may (optionally) now provide encoder settings for the recording when creating the feed with the create() function.

4. To help construct your application’s encoder settings, you can use the static AVOutputFeedFile::defaultRecordingEncoder helper function to obtain the default encoder settings. You can then modify this object to suit your needs and pass to the create() function.

Feature: VideoInputFeedV4Linux2 supports IO Mode

The VideoInputFeedV4Linux2 class now supports setting an IO mode using the ioMode() in the component’s DeviceProperties to set the mode using IOMode values.

Update: X264EncoderFeedComponent::EncoderTune constants are bit flags

With this release EncoderTune constants have been updated to be represented by bit flags rather than ordinal values. Previously SDK users could only set a single tune value, but now multiple tune values can be combined using the bitwise OR operator, using the same tune() function as before. To clear any tune options, you can use tuneNone().

using namespace PxMedia;

X264EncoderFeedComponent encoder;

// As before, you may set a single encoder tune option using the enum value
encoder.tune(X264EncoderFeedComponent::EncoderTune::ZEROLATENCY);

// New: you may combine multiple tune options using the bitwise OR operator
encoder.tune(X264EncoderFeedComponent::EncoderTune::ZEROLATENCY |
             X264EncoderFeedComponent::EncoderTune::FASTDECODE);

// New: Clear any tune options using
encoder.tuneNone();

Feature: Utility function for converting strings to media types

A utility function has been added to the SDK to convert a string to a MediaType value; see mediaTypeFromFormatString().

Fix: Proximie Context user agent can now be set

See ProximieContext::setUserAgent for more information.