Setup V2 docs for THEOlive that aren't visible yet

.prettierignore

@@ -21,6 +21,7 @@ adengine/static/ad-engine.yaml
 adengine/reference/
 millicast/api/
 theolive/api/
+theolive_versioned_docs/*/api/
 
 # Submodules
 theoplayer/external/

docusaurus.config.ts

@@ -269,6 +269,18 @@ const config: Config = {
         routeBasePath: '/theolive',
         sidebarPath: './sidebarsTheolive.ts',
         docItemComponent: '@theme/ApiItem',
+        lastVersion: 'v1',
+        versions: {
+          // TODO: Make 'current' the lastVersion when v2 docs are finalized
+          current: {
+            label: 'v2',
+            banner: 'none',
+            noIndex: true,
+          },
+          v1: {
+            label: 'v1',
+          },
+        },
       } satisfies DocsPlugin.Options,
     ],
     [
@@ -366,51 +378,23 @@ const config: Config = {
         id: 'theolive-api',
         docsPluginId: 'theolive',
         config: {
-          channels: {
-            specPath: 'theolive/api/channels.json',
-            outputDir: 'theolive/api/channels',
-            hideSendButton: false,
-            sidebarOptions: {
-              groupPathsBy: 'tag',
-            },
-            markdownGenerators: openApiLinkRewrite(),
-          },
-          events: {
-            specPath: 'theolive/api/events.json',
-            outputDir: 'theolive/api/events',
-            hideSendButton: false,
-            sidebarOptions: {
-              groupPathsBy: 'tag',
-            },
-            markdownGenerators: openApiLinkRewrite(),
-          },
-          reports: {
-            specPath: 'theolive/api/reports.json',
-            outputDir: 'theolive/api/reports',
-            hideSendButton: false,
-            sidebarOptions: {
-              groupPathsBy: 'tag',
-            },
-            markdownGenerators: openApiLinkRewrite(),
-          },
-          schedulers: {
-            specPath: 'theolive/api/schedulers.json',
-            outputDir: 'theolive/api/schedulers',
-            hideSendButton: false,
-            sidebarOptions: {
-              groupPathsBy: 'tag',
-            },
-            markdownGenerators: openApiLinkRewrite(),
-          },
-          webhooks: {
-            specPath: 'theolive/api/webhooks.json',
-            outputDir: 'theolive/api/webhooks',
+          theolive: {
+            version: 'v2',
+            label: 'v2',
+            specPath: 'https://api.theo.live/v2/api-docs/swagger.json',
+            outputDir: `theolive/api/`,
             hideSendButton: false,
             sidebarOptions: {
               groupPathsBy: 'tag',
+              sidebarCollapsible: true,
             },
             markdownGenerators: openApiLinkRewrite(),
           },
+          channels: theoLiveV1OpenApiOptions('channels'),
+          events: theoLiveV1OpenApiOptions('events'),
+          reports: theoLiveV1OpenApiOptions('reports'),
+          schedulers: theoLiveV1OpenApiOptions('schedulers'),
+          webhooks: theoLiveV1OpenApiOptions('webhooks'),
         },
       } satisfies OpenApiPlugin.PluginOptions,
     ],
@@ -625,6 +609,12 @@ const config: Config = {
           docsPluginId: 'theoplayer',
           position: 'right',
         },
+        // TODO: Enable theolive version dropdown when v2 docs are finalized
+        // {
+        //   type: 'docsVersionDropdown',
+        //   docsPluginId: 'theolive',
+        //   position: 'right',
+        // },
       ],
     },
     footer: {
@@ -705,4 +695,19 @@ function externalDocUrl(docPath: string): string {
   return `https://github.com/THEOplayer/${projectName}/blob/-/${externalDocPath}`;
 }
 
+function theoLiveV1OpenApiOptions(name: string): OpenApiPlugin.APIOptions {
+  return {
+    version: 'v1',
+    label: 'v1',
+    specPath: `theolive_versioned_docs/version-v1/api/${name}.json`,
+    outputDir: `theolive_versioned_docs/version-v1/api/${name}`,
+    hideSendButton: false,
+    sidebarOptions: {
+      groupPathsBy: 'tag',
+      sidebarCollapsible: true,
+    },
+    markdownGenerators: openApiLinkRewrite(),
+  };
+}
+
 export default config;

package.json

@@ -13,8 +13,8 @@
     "serve": "node serve.js",
     "write-translations": "docusaurus write-translations",
     "write-heading-ids": "docusaurus write-heading-ids",
-    "gen-api-docs": "docusaurus gen-api-docs all --plugin-id ads-api && docusaurus gen-api-docs all --plugin-id ad-engine-api && docusaurus gen-api-docs all --plugin-id millicast-api && docusaurus gen-api-docs all --plugin-id theolive-api",
-    "clean-api-docs": "docusaurus clean-api-docs all --plugin-id ads-api && docusaurus clean-api-docs all --plugin-id ad-engine-api && docusaurus clean-api-docs all --plugin-id millicast-api && docusaurus clean-api-docs all --plugin-id theolive-api",
+    "gen-api-docs": "docusaurus gen-api-docs all --plugin-id ads-api && docusaurus gen-api-docs all --plugin-id ad-engine-api && docusaurus gen-api-docs all --plugin-id millicast-api && docusaurus gen-api-docs all --plugin-id theolive-api --all-versions",
+    "clean-api-docs": "docusaurus clean-api-docs all --plugin-id ads-api && docusaurus clean-api-docs all --plugin-id ad-engine-api && docusaurus clean-api-docs all --plugin-id millicast-api && docusaurus clean-api-docs all --plugin-id theolive-api --all-versions",
     "typecheck": "tsc",
     "check-format": "prettier --check .",
     "format": "prettier --write .",

sidebarsTheolive.ts

@@ -1,9 +1,5 @@
 import type { SidebarsConfig } from '@docusaurus/plugin-content-docs';
-import channelsApiSidebar from './theolive/api/channels/sidebar';
-import eventsApiSidebar from './theolive/api/events/sidebar';
-import reportsApiSidebar from './theolive/api/reports/sidebar';
-import schedulersApiSidebar from './theolive/api/schedulers/sidebar';
-import webhooksApiSidebar from './theolive/api/webhooks/sidebar';
+import apiSidebar from './theolive/api/sidebar';
 
 const sidebars: SidebarsConfig = {
   theolive: [
@@ -58,47 +54,17 @@ const sidebars: SidebarsConfig = {
       customProps: {
         icon: '🛜',
       },
-      href: '/theolive/api/',
+      href: '/theolive/next/api/',
     },
   ],
   theoLiveApi: [
     {
       type: 'link',
       label: '« Back',
-      href: '/theolive/',
+      href: '/theolive/next/',
     },
     'api/index',
-    {
-      type: 'category',
-      label: 'Channel API',
-      collapsible: true,
-      collapsed: false,
-      items: channelsApiSidebar.slice(1),
-    },
-    {
-      type: 'category',
-      label: 'Events API',
-      collapsible: true,
-      items: eventsApiSidebar[1].items,
-    },
-    {
-      type: 'category',
-      label: 'Reports API',
-      collapsible: true,
-      items: reportsApiSidebar[1].items,
-    },
-    {
-      type: 'category',
-      label: 'Schedulers API',
-      collapsible: true,
-      items: schedulersApiSidebar[1].items,
-    },
-    {
-      type: 'category',
-      label: 'Webhooks API',
-      collapsible: true,
-      items: webhooksApiSidebar[1].items,
-    },
+    ...apiSidebar.slice(1),
   ],
 };
 

theolive/api/.gitignore

@@ -1,4 +1,5 @@
 # Auto-generated by `docusaurus gen-api-docs`
-**/*.mdx
+**/*.api.mdx
+**/*.info.mdx
 **/sidebar.ts
-!/*.mdx
+**/versions.json

theolive_versioned_docs/version-v1/api/.gitignore

@@ -0,0 +1,4 @@
+# Auto-generated by `docusaurus gen-api-docs`
+**/*.api.mdx
+**/*.info.mdx
+**/sidebar.ts

theolive_versioned_docs/version-v1/api/index.mdx

@@ -0,0 +1,14 @@
+---
+sidebar_label: Introduction
+---
+
+# THEOlive REST API
+
+import SidebarCategoryDocCardList from '@site/src/components/SidebarCategoryDocCardList';
+
+THEOlive provides a REST API to manage channels, receive events, create reports, and set up webhooks.
+
+Alternatively, you can perform the most common actions directly from the THEOlive management console.
+See [our getting started guide](/theolive/getting-started.mdx) for more information.
+
+<SidebarCategoryDocCardList />

theolive_versioned_docs/version-v1/callouts/_premium_feature.md

@@ -0,0 +1,5 @@
+:::warning Premium Feature
+
+This feature is a premium option that must be enabled on your account. If you would like to use this capability on your project, please [submit a support ticket](https://support.dolby.io/hc/en-au) or reach out to your [sales/solutions](https://optiview.dolby.com/contact/) contact.
+
+:::

theolive_versioned_docs/version-v1/contribution/hardware-encoders/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "Hardware Encoders",
+  "position": 4
+}

theolive_versioned_docs/version-v1/contribution/hardware-encoders/haivision.mdx

@@ -0,0 +1,48 @@
+---
+title: Haivision
+slug: /hardware-encoders/haivision
+---
+
+**Haivision** provides professional broadcasting equipment to the streaming industry. The KB series of H.264 & HEVC Internet Media Encoders and Transcoders deliver high-quality video streaming for resolutions up to 4K, available as small form factor portable appliances as well as rack-mountable enterprise-grade servers. The KB Series provides you with multiple options for live event streaming, helping you deliver the highest quality live video to your global internet audience.
+
+See the official [Haivision](https://www.haivision.com/) site for documentation, installation instructions, and additional support.
+
+## Haivision KB
+
+To get started, log into your Dolby OptiView dashboard. Enter your KB web interface, switch views to the Channel Control Center, and create a new channel.
+
+Follow the Create Channel Wizard prompts to create a channel as normal:
+
+1. Enter the desired channel name.
+2. Identify your live source for the channel input.
+3. Choose RTMP for the channel output and copy the RTMP publish path from the Dolby _channel_ you have created.  
+   RTMP URL: `rtmps://rtmp.<my-channel-region>.hesp.live/live`
+4. Enter the RTMP publish stream name from the ingest server section.  
+   Stream Name: `<my-stream-key>`
+
+import RtmpPush from '../../assets/img/hardware-encoders/theolive-ingest-server-rtmp-push.png';
+
+<div class="center-container">
+  <img src={RtmpPush} width="500" />
+</div>
+
+With the broadcast credentials set up, the stream is ready to go live. To view the stream, scroll down to the _Playout configurations_ section in your channel page and start the player.
+
+## Recommended settings
+
+Here are some adjustments recommended by the [Haivision support](https://www.haivision.com/support/) team:
+
+| Settings Location                        | Recommendation                                     |
+| :--------------------------------------- | :------------------------------------------------- |
+| In Input settings                        | Change Timestamps from System Time to Zero-Based\* |
+| In Video Encoder settings > Settings tab | Change the Framing from IBBP to IP                 |
+| In the Advanced tab                      | Change the Codec Present to Baseline               |
+| Set GOP                                  | Fixed Mode with 2000ms                             |
+| Set Entropy coding mode                  | CABAC                                              |
+| Set Recommended Bitrate                  | 6,000 @ 1080p or 4,500 @ 720p                      |
+
+\*Note: The timestamp seeding seemed to be the magic change on the KBs.
+
+:::info 🚧 Frame rate and bandwidth
+Remember to set the frame rate to the same value as in your THEOlive channel ingest configuration and make sure that your encoder has a stable connection and enough upload bandwidth. See [Stream configuration](../stream-configuration.mdx) for more details.
+:::

theolive_versioned_docs/version-v1/contribution/hardware-encoders/index.mdx

@@ -0,0 +1,44 @@
+---
+title: Hardware Encoders
+description: Hardware-based Encoders for Broadcasting Live Streaming Content
+slug: /hardware-encoders
+---
+
+In today's digital landscape, the demand for live streaming content has skyrocketed, prompting broadcasters and video creators to prioritize the efficient delivery of high-quality video and audio streams. Hardware-based encoders play a crucial role in this process with their offerings of superior encoding capabilities and seamless transmission. Needless to say, workflows don't have to be interrupted in order to better a stream.
+
+## Integration guides
+
+Review these guides for how to setup your preferred tools for live streaming integrations.
+
+import { IconGrid, IconGridButton } from '@site/src/components/IconGrid';
+
+<IconGrid>
+  <IconGridButton large>[![Haivision](../../assets/img/hardware-encoders/haivision_logo.jpeg)](haivision.mdx)</IconGridButton>
+  <IconGridButton large>[![Magewell](../../assets/img/hardware-encoders/magewell_logo.jpeg)](magewell.mdx)</IconGridButton>
+  <IconGridButton large>[![Osprey](../../assets/img/hardware-encoders/osprey_logo.jpeg)](osprey.mdx)</IconGridButton>
+  <IconGridButton large>[![Videon](../../assets/img/hardware-encoders/videon_central_logo.jpeg)](videon.mdx)</IconGridButton>
+</IconGrid>
+
+### Haivision
+
+[How-to integrate using Haivision KB Encoder](haivision.mdx)
+
+The **Haivision KB Encoder** is a high-performance video encoding device that efficiently converts video signals into compressed formats for reliable live streaming and distribution over IP networks.
+
+### Magewell
+
+[How-to integrate using Magewell Ultra Encode](magewell.mdx)
+
+The **Magewell Ultra Encode** is a leading encoder manufacturer that supports connecting to the Dolby OptiView Streaming Service for broadcasting real-time streams.
+
+### Osprey
+
+[How-to integrate using Osprey Talon Encoder](osprey.mdx)
+
+**Osprey Talon** is a form-factor H.264 (AVC) and H.265 (HEVC) encoder designed to be easy to use, portable, and easily stream low latency 4k and UHD video encoding from SDI and HDMI.
+
+### Videon
+
+[How-to integrate using Videon EdgeCaster](videon.mdx)
+
+**Videon EdgeCaster** is a versatile and powerful edge compute encoder that securely delivers high-quality live video streams to multiple platforms simultaneously, offering a comprehensive solution for efficient video distribution.

theolive_versioned_docs/version-v1/contribution/hardware-encoders/magewell.mdx

@@ -0,0 +1,50 @@
+---
+title: 'Magewell'
+slug: /hardware-encoders/magewell
+hide_table_of_contents: true
+---
+
+**Magewell** is a leading encoder manufacturer that supports connecting to the Dolby OptiView Streaming platform for broadcasting live streams. This guide outlines how to broadcast streams from a [Magewell](https://www.magewell.com/) device to the Dolby OptiView platform.
+
+See the official [Magewell site](https://www.magewell.com/support-contacts) for documentation, installation instructions, and additional support.
+
+## Ultra Encode
+
+The [Magewell Ultra Encode](https://www.magewell.com/ultra-encode) supports broadcasting RTMP streams, which can be ingested by the Dolby.io Real-time Streaming service.
+
+To begin, first power on your Ultra Encode, connect it to the internet (Ethernet or WiFi), and connect your video capture device. Once connected, [log in](https://www.magewell.com/files/documents/User_Manual/ultra_encode_user_manual_en.pdf) to the Ultra Encode dashboard and navigate to the `Streaming Server` tab on the left side panel. Inside of `Streaming Server` click the `+ Add Server` button and select `RTMP`.
+
+import RtmpMagewell from '../../assets/img/hardware-encoders/magewell-rtmp.png';
+
+<div class="center-container">
+  <img src={RtmpMagewell} width="600" />
+</div>
+
+- For the `URL` select `rtmps://` and enter the **URL** of the channel.  
+  RTMP URL: `rtmps://rtmp.<my-channel-region>.hesp.live/live`
+- For the `Stream key` input the **Stream key** from the ingest server section.  
+  Stream key: `<my-stream-key>`
+
+Finally, select which network you'd like the encoder to use to connect, and save the settings.
+
+import RtmpDolbyMagewell from '../../assets/img/hardware-encoders/magewell-rtmp-live.png';
+
+<div class="center-container">
+  <img src={RtmpDolbyMagewell} width="600" />
+</div>
+
+Once saved, make sure the stream is activated by toggling the server switch on the `Streaming Server` page.
+
+import ConnectMagewell from '../../assets/img/hardware-encoders/magewell-connect.png';
+
+<div class="center-container">
+  <img src={ConnectMagewell} width="600" />
+</div>
+
+With the stream enabled, you can navigate back to the main Dashboard page of the encoder and see your stream connect.
+
+import ConnectMagewellStream from '../../assets/img/hardware-encoders/magewell-connect-stream.png';
+
+<div class="center-container">
+  <img src={ConnectMagewellStream} width="600" />
+</div>