5.2.4. Release notes for v0.8

About release 0.8

The 0.8 release of Proximie SDK targets session life cycle and error handling improvements, as well as some API updates for consistency and ease of use.

NOTE: The 0.8 release introduces some minor breaking changes, please see the notes below.

v0.8.3

Minor breaking change

Due to a minor change in the Proximie REST API return payloads for sessions, applications that wish to check the session status (usually to check if the session is ACTIVE) should now consult the session rather than the stream member.

Before:

for (const auto& item : sessions->sessions) {
  // Note: using the stream member and Stream::Status enum
  if (item.stream.statusIs(PxRestApi::Stream::Status::ACTIVE)) {
    // ...

Now:

for (const auto& item : sessions->sessions) {
  // Note: using session member and Session::Status enum
  if (item.session.statusIs(PxRestApi::Session::Status::ACTIVE)) {
    // ...

Fixes in this release

Previously a stopped feed would not fully shut down the pipeline, meaning it would still reference any resources - e.g. a web-cam input would not be free for other feeds to use. Now, stopped feeds fully free their pipelines/resources.

Feature: Incoming UDP video support

The SDK now supports incoming video feeds over UDP, using the video input component VideoInputFeedUdp (see the class documentation for details). Since this class is a kind of VideoInputFeedComponent it can be used anywhere existing video input components are used (e.g. could replace an existing VideoInputFeedV4Linux2 value).

Feature: Utility feeds

The SDK now supports “utility feeds” - feeds that are stand-alone and do not require a session. The first utility feed is UtilityVideoLocalFeed, which can be used to take a local video input (e.g. the webcam) and output it (e.g. to a window) - this could be used to test/debug feeds and pipelines without needing a session, or to preview a feed before connecting it to a session.

The demo has been updated to demonstrate exactly this: it shows the webcam in a local window before initiating the authentication process. Once authenticated, the utility feed is closed and the webcam is then streamed into the session as before.

See the Utility Feeds development guide for more details.

v0.8.2

Feature: Feed “stage” for video rotation & cropping

The SDK now supports video rotation and cropping for both local and remote feeds. See the Feed Stages development guide for more details.

Known issues in this release

We have identified an issue combining rotation followed by cropping with larger cropping values compared to the video resolution. This appears to be an issue with the underlying GStreamer elements used by the the SDK, namely videoflip and videocrop.

An example of the issue is when rotating 90 degrees and cropping by an amount that exceeds the pre-rotated resolution - e.g after rotating a 640x480 video, vertical cropping may not exceed 480 pixels despite the rotated vertical resolution actually being 640 pixels.

This can be repeated with a GStreamer command line:

gst-launch-1.0 videotestsrc ! video/x-raw,height=480,width=640 ! videoflip method=clockwise ! videocrop bottom=480 ! videoconvert ! autovideosink

A crop value below 480 pixels will work as expected, but above 480 pixels will cause a hard fail.

Inverting the order and cropping in the other direction before rotating, which should have the same outcome, does not exhibit the issue:

gst-launch-1.0 videotestsrc ! video/x-raw,height=480,width=640 ! videocrop left=480 ! videoflip method=clockwise ! videoconvert ! autovideosink

Demo updates

The demo now supports video rotation and cropping for both local and remote feeds. To help manage feature demonstration, the demo takes command line options/ environment variable settings to enable/disable certain features:

Description	Command line option	Environment variable
Enable adaptive streaming demonstration	`--demo-adaptive`	`PXSDK_DEMO_ADAPTIVE`
Enable using the SDK to rotate the web-cam	`--demo-rotate`	`PXSDK_DEMO_ROTATE`

For these switch options, use the form --option=on to enable the feature.

v0.8.1

Boost 1.86

This build has been updated to use the latest version of Boost. See Boost Version 1.86.0 for details of updates and changes to the Boost library.

v0.8.0

Fixes in this release

Fixed an issue with WebRTC stats not being successfully parsed with GStreamer 1.24+

New features

Disconnecting from sessions

FeedManager now has the disconnectFromSession() method, which allows the feed manager to cleanly shut down and disconnect from a session. There is also a notification onSessionDisconnected() that can be used to respond to disconnection events.

See the Media Server Session development guide for more details.

New feature: provide format details when using x-raw video

Previously the SDK only supported x-raw video without being able to specify the format. Now, the MediaType enumeration used to define video capabilities has been extended to include more formats, e.g. VIDEO_XRAW_NV12. See the documentation for MediaType the full list of supported raw formats.

New feature: improved error handling for network issues

In this release, the SDK has much improved handling for network issues. If the network conditions cause a failure in the media session with a Feed Manager, it will gracefully shut down and report the error to the application with the onSessionDisconnected() callback.

Breaking changes

Minor breaking change: setting encoders

When setting video and audio encoders with the FeedManager using videoEncoder() and audioEncoder(), pass a plain encoder object instead of needing to move a unique pointer.

Before:

// Before we used a unique pointer
auto h264 = std::make_unique<Proximie::PxMedia::VideoWebRtcEncodeFeedH264>();
h264->encodingProperties().bitrate(H264_BITRATE);
feedMgr->videoEncoder(std::move(h264));

Now:

// Now we use a plain object
Proximie::PxMedia::VideoWebRtcEncodeFeedH264 h264;
h264.encodingProperties().bitrate(H264_BITRATE);
feedMgr->videoEncoder(h264);

Minor breaking change: Feed manager event parameters

Some event parameter types have changed from references to shared pointers for efficiency and reduced value copying.

onFeedStatistics() previously took a reference to a FeedStatistics, now takes a non-null pointer.

Before:

// Before took a reference to the stats
feedMgr->onFeedStatistics([](const FeedManager::FeedStatistics& stats) {
  // ...Access stats with dot operator

Now:

// Now takes a shared pointer to the stats
feedMgr->onFeedStatistics([](auto stats) {
  // ...Access stats with -> operator

onNewRemoteFeed() previously took a separate id and FeedMetadata object, now just a non-null shared pointer to FeedMetadata which has the id included within it.

Before:

// Before took an id and reference to the metadata
feedMgr->onNewRemoteFeed([](string_view id, const FeedManager::FeedMetadata& info) {
  // ...Access info with dot operator

Now:

// Now takes a shared pointer to the metadata
feedMgr->onNewRemoteFeed([](auto info) {
  // ...Access info with -> operator
  // The id is now obtained using info->streamId

Minor breaking change: Error code changes

StateCannotConnect has been replaced with more specific connection errors:

SessionActive when try to connect when already connected or connecting.
PluginConnectionActive and PluginConnectionClosed for feed plugin connection errors.

Minor breaking change: Feed manager ConnectionState

FeedManager::ConnectionState is now an alias to a general purpose enum PxMedia::ConnectionState, which has been updated to reflect the updated life cycle:

DISCONNECTING has been added to indicate an existing session is closing.
DISCONNECTED has been removed, the feed manager returns to the READY state when disconnected.

Other changes

Logging changes

SDK now outputs GStreamer pipeline logging as INFO level, making it easier to find amongst the log output.

Demo changes

UDP ports for multiple feeds

The demo previous only allowed a single incoming remote feed, which would be to the default UDP port 5004. The demo now allows for multiple incoming feeds, and the UDP port value is advanced for each subsequent feed.

The demo also supports setting the default base UDP port using command line option --base-udp-port or environment variable PXSDK_BASE_UDP_PORT.

Demo duration

The demo now runs for 30 seconds rather than 10 seconds.