Merge pull request #11 from DolbyIO/rts

New Real-time Streaming API

Author: FabienLavocat

.github/workflows/publish-package-to-pypi.yml

@@ -11,7 +11,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
     - name: Checkout 🛎️
-      uses: actions/checkout@v2.3.4
+      uses: actions/checkout@v3
       with:
         persist-credentials: false
 
@@ -35,7 +35,7 @@ jobs:
 
     - name: Deploy to PyPI 🚀
       if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags')
-      uses: pypa/gh-action-pypi-publish@v1.4.2
+      uses: pypa/gh-action-pypi-publish@release/v1
       with:
         user: __token__
         password: ${{ secrets.PYPI_API_TOKEN }}

cli/src/dolbyio_rest_apis_cli/communications/commands/streaming.py

@@ -43,8 +43,8 @@ def add_arguments(sub_parsers: _SubParsersAction) -> None:
 	)
 
     parser.add_argument(
-		'-u', '--urls',
-		help='List of RTMP endpoint URLs.',
+		'-u', '--url',
+		help='The destination URI provided by the RTMP service.',
 		nargs='*',
         required='start' in sys.argv and 'rtmp' in sys.argv,
 		type=str
@@ -55,18 +55,17 @@ async def execute_command(args: Namespace) -> None:
     cid = args.cid
     action = args.action
     target = args.target
-    urls = args.urls
+    url = args.url
 
     if target == 'rtmp':
         if action == 'start':
             print(f'Start the streaming to RTMP for the conference "{cid}".')
-            for url in urls:
-                print(f' - {url}')
+            print(f' - {url}')
 
             await streaming.start_rtmp(
                 access_token=access_token,
                 conference_id=cid,
-                rtmp_urls=urls
+                rtmp_url=url
             )
         elif action == 'stop':
             print(f'Stop the streaming to RTMP for the conference "{cid}".')

client/README.md

@@ -7,7 +7,7 @@ Python wrapper for the dolby.io REST [Communications](https://docs.dolby.io/comm
 Check the [dolbyio-rest-apis](https://pypi.org/project/dolbyio-rest-apis/) package on PyPI. To install the latest stable python package run the following command: 
 
 ```bash
-python3 -m pip install  dolbyio-rest-apis
+python3 -m pip install dolbyio-rest-apis
 ```
 
 Upgrade your package to the latest version:

client/src/dolbyio_rest_apis/communications/conference.py

@@ -41,7 +41,7 @@ async def create_conference(
         rtcp_mode: (Optional) Specifies the bitrate adaptation mode for the video transmission.
         ttl: (Optional) Specifies the time to live that enables customizing the waiting time
             (in seconds) and terminating empty conferences.
-        video_codec: (Optional) Specifies video codecs (VP8 or H264) for a specific conference.
+        video_codec: (Optional) Specifies the video codec (VP8 or H264) for the conference.
         participants: List of the :class:`Participant` object to update the permissions.
         recording_formats: If specified, the default RecordingConfiguration is overridden.
             Specifies the recording format. Valid values are 'mp3' and 'mp4'.

client/src/dolbyio_rest_apis/communications/streaming.py

@@ -7,32 +7,31 @@
 
 from dolbyio_rest_apis.communications.internal.http_context import CommunicationsHttpContext
 from dolbyio_rest_apis.communications.internal.urls import get_comms_url_v2
-from typing import List
+from dolbyio_rest_apis.core.helpers import add_if_not_none
 
 async def start_rtmp(
         access_token: str,
         conference_id: str,
-        rtmp_urls: List[str],
+        rtmp_url: str,
     ) -> None:
     r"""
     Starts the RTMP live stream for the specified conference. Once the Dolby.io Communications APIs service starts
     streaming to the target url, a `Stream.Rtmp.InProgress` Webhook event will be sent.
-    You must use this API if the conference is protected using enhanced conference access control.
 
     See: https://docs.dolby.io/communications-apis/reference/start-rtmp
 
     Args:
         access_token: Access token to use for authentication.
         conference_id: Identifier of the conference.
-        rtmp_urls: List of the RTMP endpoints where to send the RTMP stream to.
+        rtmp_url: The destination URI provided by the RTMP service.
 
     Raises:
         HttpRequestError: If a client error one occurred.
         HTTPError: If one occurred.
     """
 
     payload = {
-        'uri': '|'.join(rtmp_urls),
+        'uri': rtmp_url,
     }
 
     async with CommunicationsHttpContext() as http_context:
@@ -47,8 +46,7 @@ async def stop_rtmp(
         conference_id: str,
     ) -> None:
     r"""
-    Stops an RTMP stream.
-    You must use this API if the conference is protected using enhanced conference access control.
+    Stops the RTMP stream of the specified conference.
 
     See: https://docs.dolby.io/communications-apis/reference/stop-rtmp
 
@@ -67,22 +65,28 @@ async def stop_rtmp(
             url=f'{get_comms_url_v2()}/conferences/mix/{conference_id}/rtmp/stop'
         )
 
-async def start_lls(
+async def start_rts(
         access_token: str,
         conference_id: str,
         stream_name: str,
         publishing_token: str,
+        layout_url: str=None,
     ) -> None:
     r"""
-    Starts a Low Latency Stream to Millicast.
+    Starts real-time streaming using Dolby.io Real-time Streaming services (formerly Millicast).
 
-    See: https://docs.dolby.io/communications-apis/reference/start-rtmp
+    See: https://docs.dolby.io/communications-apis/reference/start-rts
 
     Args:
         access_token: Access token to use for authentication.
         conference_id: Identifier of the conference.
-        stream_name: The Millicast stream name to which the conference will broadcasted.
-        publishing_token:The Millicast publishing token used to identify the broadcaster.
+        stream_name: The Dolby.io Real-time Streaming stream name to which the conference is broadcasted.
+        publishing_token: The publishing token used to identify the broadcaster.
+        layout_url: Overwrites the layout URL configuration:
+            null: uses the layout URL configured in the dashboard
+                (if no URL is set in the dashboard, then uses the Dolby.io default)
+            default: uses the Dolby.io default layout
+            URL string: uses this layout URL
 
     Raises:
         HttpRequestError: If a client error one occurred.
@@ -93,22 +97,23 @@ async def start_lls(
         'stream_name': stream_name,
         'publishingToken': publishing_token,
     }
+    add_if_not_none(payload, 'layoutUrl', layout_url)
 
     async with CommunicationsHttpContext() as http_context:
         await http_context.requests_post(
             access_token=access_token,
-            url=f'{get_comms_url_v2()}/conferences/mix/{conference_id}/lls/start',
+            url=f'{get_comms_url_v2()}/conferences/mix/{conference_id}/rts/start',
             payload=payload,
         )
 
-async def stop_lls(
+async def stop_rts(
         access_token: str,
         conference_id: str,
     ) -> None:
     r"""
-    Stops an existing Low Latency Stream to Millicast.
+    Stops real-time streaming to Dolby.io Real-time Streaming services.
 
-    See: https://docs.dolby.io/communications-apis/reference/stop-lls
+    See: https://docs.dolby.io/communications-apis/reference/stop-rts
 
     Args:
         access_token: Access token to use for authentication.
@@ -122,5 +127,5 @@ async def stop_lls(
     async with CommunicationsHttpContext() as http_context:
         await http_context.requests_post(
             access_token=access_token,
-            url=f'{get_comms_url_v2()}/conferences/mix/{conference_id}/lls/stop'
+            url=f'{get_comms_url_v2()}/conferences/mix/{conference_id}/rts/stop'
         )