Release Notes

1// The current implementation of `TimeShift` leverages HLS chunks.
2// It is possible that retrieval of such chunks can take a very long time.
3// This will impact playback if the playback head catches up with the end
4// of the prefetch window, which will lead to a stall.
5// By default, a timeout of 10 seconds for each chunk retrieval is used
6// to avoid holding off playback for too long (worst case a chunk will be
7// skipped and playback may pause temporarily).
8// This timeout is configurable by setting the following option (it defaults
9// to 0, which indicates that we should use the internal default):
10var timeoutInMilliseconds = 5000L
11rendererOptions.timeShiftOptions.chunkRetrievalTimeoutInMilliseconds
12  = timeoutInMilliseconds

1import com.phenixrts.common.Disposable;
2import com.phenixrts.pcast.Renderer;
3import com.phenixrts.pcast.TimeShift;
4
5import java.util.Date;
6
7// Renderer has been obtained from `MediaStream` or `ExpressSubscriber`:
8var renderer: Renderer = ...
9
10
11if (!renderer.isSeekable) {
12    // This stream does not support time shifting
13    return;
14}
15
16// Must be in UTC:
17var timePoint = Date(...)
18
19var timeShift = renderer.seek(timePoint)
20
21// Observe ready status and call `loop` once TimeShift is ready.
22// This ensures that when `loop` is called playback will start
23// instantly.
24
25// All observables return a `Disposable` object. This needs to be stored
26// in order to keep the observable subscription alive.
27// It is recommended to make this a member of the enclosing class
28var disposables = mutableListOf<Disposable>()
29
30timeShift.observableReadyForPlaybackStatus.subscribe { isReady ->
31    if (isReady) {
32        var loopDurationInMilliseconds = 30000L
33
34        timeShift.loop(loopDurationInMilliseconds)
35    }
36}.run{ disposables.add(this) }
37
38// When time shifted viewing is no longer desired:
39
40// Dispose the `TimeShift` object. It will no longer be useable
41// after this operation. A new instance can be obtained via `seek`
42timeShift.dispose()  // <-- Playback will jump back to real-time head
43
44// It is also possible to stop a timeshift in progress so it can
45// be used again by calling `loop` later
46timeShift.stop()  // <-- Playback will jump back to real-time head
47
48// After `stop()` the ready status will (briefly) switch to false, then
49// back to true when enough data has been re-cached.
50
51// `TimeShift` objects can fail, either during creating when passing in
52// an invalid timestamp to `Renderer.seek()` or any of the other `TimeShift`
53// method. Once a `TimeShift` has failed, it should be disposed and a new
54// one created.
55timeShift.observableFailure.subscribe { status ->
56    // a non-OK `RequestStatus` is returned here
57}.run { disposables.add(this) }
58
59// Pause playback
60timeShift.pause()
61
62// Resume playback after pause
63timeShift.play()
64
65// The current playback head can be observed. Each video frame will trigger
66// the observable. The head is reported as a `Date` object and represents UTC.
67timeShift.observablePlaybackHead.subscribe { playbackHead ->
68    // a `Date` object. Avoid blocking this thread and dispatch UI updates
69    // as needed.
70}.run { disposables.add(this) }
71
72// `TimeShift` supports seeking to any location within the current segment.
73// The segment is defined by:
74// Start: Time point passed into `Renderer.seek`
75// End  : Start plus duration passed into `TimeShift.loop`
76
77// Seeking is only possible if the `TimeShift` is either stopped or paused.
78// Once `TimeShift` is ready for playback, the observable returned by `seek`
79// will return a status code. Call `play()` to start/resume playback if the
80// status is OK.
81var relativeSeekTimeInMillis = -10000L  // Seeks back 10 seconds
82
83timeShift.seek(relativeSeekTimeInMillis).subscribe { status ->
84    if (status == RequestStatus.OK) {
85      timeShift.play()
86    } else {
87        // Handle error. In most cases the seek argument would have led to
88        // a location outside of the segment
89    }
90}.run { disposables.add(this) }
91
92// There is also a second version of `seek` available, which accepts a `Date`
93// as its argument representing an absolute time point in UTC (also has to
94// fall within the boundaries of the segment).
95
96
97// A `TimeShift` stream generally consists of several so called layers. Layers
98// have different bitrates, usually by varying resolution and framerate (lower
99// bitrate layers tend to have lower resolutions and/or framerates).
100
101// While a `TimeShift` is playing back content, it will automatically select
102// an appropriate layer based on the pixel resolution of the rendering
103// surface. The logic attempts to select a layer, whose resolution matches
104// that of the rendering surface as closely as possible.
105
106// Sometimes an app may want to further restrict the playback layer in order
107// to reduce battery usage for instance. This is possible via the
108// `TimeShift.limitBandwidth` API. It forces the `TimeShift` to only select
109// layers with an average bitrate less or equal to the value passed into
110// `limitBandwidth`.
111// The limitation will remain in effect for as long as the app holds on to
112// the `Disposable` object returned by the API.
113// This API can be called at any time: before and during playback.
114var bandwithLimitInBps = 400000L
115
116var limitBandwidthDisposable = timeShift?.limitBandwidth(bandwithLimitInBps)
117
118// Call `dispose()` on the `Disposable` object to release the bandwidth limit
119limitbandwidthDisposable?.dispose()
120
121
122// Certain behaviors of `TimeShift` can be changed by passing in
123// custom options when the `Renderer` is created:
124
125var rendererOptions = RendererOptions()
126
127// When calling `Renderer.seek` or `TimeShift.seek` the
128// bandwidth will be automatically limited to shorten the amount of time
129// it takes for the `TimeShift` object to become ready.
130// The downside of this approach is that once the playback starts, it will
131// do so on a lower bitrate rendition of the stream and it generally takes a
132// few seconds before the rendition switches to a higher bitrate.
133// This behavior is enabled by default, but can be disabled by setting the
134// following option to false:
135rendererOptions.timeShiftOptions.lowerBandwidthWhileSeekingEnabled = false
136
137// The size of the viewport will determine which rendition of the stream is
138// selected (the rendition whose height in pixels is closest to the current
139// height of the viewport). This selection process is continuous, which means
140// that as the viewport size changes, so does the selected rendition.
141// After a new rendition has been selected, it will not render frames
142// instantly. Instead, it will take up to about 5 seconds before it will
143// render frames.
144// This behavior is enabled by default, but can be disabled by setting the
145// following option to false:
146rendererOptions.timeShiftOptions.viewportSizeBasedRenditionSelectionEnabled
147  = false
148
149// The options object can be passed in directly to the `createRenderer`
150// method:
151var subscriber: ExpressSubscriber = ... // previously obtained
152
153var renderer = subscriber.createRenderer(rendererOptions)
154
155// Alternatively, it can be passed via various options builders, for example
156// for `joinChannel`:
157var joinChannelOptionsBuilder =
158   ChannelExpressFactory.createJoinChannelOptionsBuilder()
159
160joinChannelOptionsBuilder.withRendererOptions(rendererOptions)

1try {
2      Os.setenv("PHENIX_AUDIO_PLAYBACK_SAMPLE_RATE_OVERRIDE", "16000", true);
3      Os.setenv("PHENIX_AUDIO_RECORDING_SAMPLE_RATE_OVERRIDE", "8000", true);
4    } catch (ErrnoException e) {
5      // handle exception
6    }

1AudioManager audioManager = (AudioManager)getSystemService(Context.AUDIO_SERVICE);
2
3    // call at appropriate time - detection of BT on
4    audioManager.startBluetoothSco();
5
6    // call at appropriate time - detection of BT off
7    audioManager.stopBluetoothSco();

1// publishing
2    final UserMediaOptions mediaConstraints = new UserMediaOptions();
3    mediaConstraints.getAudioOptions().capabilityConstraints.put(
4            DeviceCapability.AUDIO_ECHO_CANCELATION_MODE,
5            singletonList(new DeviceConstraint(AudioEchoCancelationMode.ON)));
6    PublishOptions publishOptions = PCastExpressFactory.createPublishOptionsBuilder()
7        .withMediaConstraints(mediaConstraints)
8        // add any other options
9        .buildPublishOptions();
10    // subscribing
11    final RendererOptions rendererOptions = new RendererOptions();
12    rendererOptions.audioEchoCancelationMode = AudioEchoCancelationMode.ON;
13    JoinChannelOptionsBuilder joinChannelOptionsBuilder = ChannelExpressFactory
14        .createJoinChannelOptionsBuilder()
15        .withRendererOptions(rendererOptions)
16        // add any other options
17        .buildJoinChannelOptions()

1import com.phenixrts.chat.RoomChatServiceFactory;
2import com.phenixrts.room.RoomService;
3
4final int batchSize = ...
5final RoomService roomService = ...; // previously obtained
6
7final HashSet<String> wantedMimeTypes = new HashSet<String>();
8wantedMimeTypes.add(“text/javascript”);
9
10final RoomChatService chatService =
11    RoomChatServiceFactory.createRoomChatService(
12        roomService,
13        batchSize,
14        wantedMimeTypes
15    );
16
17// “chatService” retrieves only messages of “wantedMimeTypes”
18final Disposable subscriptionLastChatMessage =
19    chatService.getObservableLastChatMessage().subscribe((change) -> {
20    final ChatMessage message = (ChatMessage)change;
21    assert message.getObservableMimeType().getValue() == “text/javascript”;
22});
23
24final Disposable subscriptionChatMessages =
25    chatService.getObservableChatMessages().subscribe((change) -> {
26    final ChatMessage[] messages = (ChatMessage[])change;
27
28    for (int i = 0; i < messages.length; ++i) {
29        assert message.getObservableMimeType().getValue() ==
30               “text/javascript”;
31    }
32});
33
34chatService.getMessages(
35    batchSize,
36    afterMessageId,
37    beforeMessageId,
38    (RoomChatService service, ChatMessage[] messages, RequestStatus status) -> {
39   for (int i = 0; i < messages.length; ++i) {
40        assert message.getObservableMimeType().getValue() ==
41               “text/javascript”;
42    }
43});
44
45// send message with a specific MIME type
46// with just the message, MIME type defaults to “text/plain”:
47chatService.sendMessageToRoom("My First Message");
48
49// with message and MIME type, but using default callback
50chatService.sendMessageToRoom("My First Message", "text/javascript");
51
52// with message, MIME type, and callback
53chatService.sendMessageToRoom(
54    "My First Message",
55    "text/javascript",
56    (RequestStatus status, String message) -> { ... }
57);