diff --git a/.prettierignore b/.prettierignore index 39b1dcf59c69..9b93b4abaee6 100644 --- a/.prettierignore +++ b/.prettierignore @@ -21,6 +21,7 @@ adengine/static/ad-engine.yaml adengine/reference/ millicast/api/ theolive/api/ +theolive_versioned_docs/*/api/ # Submodules theoplayer/external/ diff --git a/docusaurus.config.ts b/docusaurus.config.ts index 449a9fe7d968..05f9f764fca3 100644 --- a/docusaurus.config.ts +++ b/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; diff --git a/package.json b/package.json index cbe10dcce49e..986bd64e4d97 100644 --- a/package.json +++ b/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 .", diff --git a/sidebarsTheolive.ts b/sidebarsTheolive.ts index a1239ab0e2ed..0b63419a4f8e 100644 --- a/sidebarsTheolive.ts +++ b/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), ], }; diff --git a/theolive/api/.gitignore b/theolive/api/.gitignore index 4ea464c8cf6d..ef3434b3a3c6 100644 --- a/theolive/api/.gitignore +++ b/theolive/api/.gitignore @@ -1,4 +1,5 @@ # Auto-generated by `docusaurus gen-api-docs` -**/*.mdx +**/*.api.mdx +**/*.info.mdx **/sidebar.ts -!/*.mdx +**/versions.json diff --git a/theolive_versioned_docs/version-v1/api/.gitignore b/theolive_versioned_docs/version-v1/api/.gitignore new file mode 100644 index 000000000000..4a56957b52d8 --- /dev/null +++ b/theolive_versioned_docs/version-v1/api/.gitignore @@ -0,0 +1,4 @@ +# Auto-generated by `docusaurus gen-api-docs` +**/*.api.mdx +**/*.info.mdx +**/sidebar.ts diff --git a/theolive/api/channels.json b/theolive_versioned_docs/version-v1/api/channels.json similarity index 100% rename from theolive/api/channels.json rename to theolive_versioned_docs/version-v1/api/channels.json diff --git a/theolive/api/events.json b/theolive_versioned_docs/version-v1/api/events.json similarity index 100% rename from theolive/api/events.json rename to theolive_versioned_docs/version-v1/api/events.json diff --git a/theolive_versioned_docs/version-v1/api/index.mdx b/theolive_versioned_docs/version-v1/api/index.mdx new file mode 100644 index 000000000000..a5251b82247b --- /dev/null +++ b/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. + + diff --git a/theolive/api/reports.json b/theolive_versioned_docs/version-v1/api/reports.json similarity index 100% rename from theolive/api/reports.json rename to theolive_versioned_docs/version-v1/api/reports.json diff --git a/theolive/api/schedulers.json b/theolive_versioned_docs/version-v1/api/schedulers.json similarity index 100% rename from theolive/api/schedulers.json rename to theolive_versioned_docs/version-v1/api/schedulers.json diff --git a/theolive/api/webhooks.json b/theolive_versioned_docs/version-v1/api/webhooks.json similarity index 100% rename from theolive/api/webhooks.json rename to theolive_versioned_docs/version-v1/api/webhooks.json diff --git a/theolive_versioned_docs/version-v1/assets/img/0ab3624-1b.PNG b/theolive_versioned_docs/version-v1/assets/img/0ab3624-1b.PNG new file mode 100644 index 000000000000..a0e52cb2f889 Binary files /dev/null and b/theolive_versioned_docs/version-v1/assets/img/0ab3624-1b.PNG differ diff --git a/theolive_versioned_docs/version-v1/assets/img/17980ac-Wirecast_-_Output_Settings.jpg b/theolive_versioned_docs/version-v1/assets/img/17980ac-Wirecast_-_Output_Settings.jpg new file mode 100644 index 000000000000..34b54a5a8b0b Binary files /dev/null and b/theolive_versioned_docs/version-v1/assets/img/17980ac-Wirecast_-_Output_Settings.jpg differ diff --git a/theolive_versioned_docs/version-v1/assets/img/22fb225-my-team.PNG b/theolive_versioned_docs/version-v1/assets/img/22fb225-my-team.PNG new file mode 100644 index 000000000000..73099e52128e Binary files /dev/null and b/theolive_versioned_docs/version-v1/assets/img/22fb225-my-team.PNG differ diff --git a/theolive_versioned_docs/version-v1/assets/img/230b3c5-platform-panel2.png b/theolive_versioned_docs/version-v1/assets/img/230b3c5-platform-panel2.png new file mode 100644 index 000000000000..d2269c59b410 Binary files /dev/null and b/theolive_versioned_docs/version-v1/assets/img/230b3c5-platform-panel2.png differ diff --git a/theolive_versioned_docs/version-v1/assets/img/2416285-Wirecast_-_Start_Streaming.jpg b/theolive_versioned_docs/version-v1/assets/img/2416285-Wirecast_-_Start_Streaming.jpg new file mode 100644 index 000000000000..51f18dafd1b6 Binary files /dev/null and b/theolive_versioned_docs/version-v1/assets/img/2416285-Wirecast_-_Start_Streaming.jpg differ diff --git a/theolive_versioned_docs/version-v1/assets/img/302e789-dashboard.png b/theolive_versioned_docs/version-v1/assets/img/302e789-dashboard.png new file mode 100644 index 000000000000..226677ba7092 Binary files /dev/null and b/theolive_versioned_docs/version-v1/assets/img/302e789-dashboard.png differ diff --git a/theolive_versioned_docs/version-v1/assets/img/3030fa6-4.Whole_team.PNG b/theolive_versioned_docs/version-v1/assets/img/3030fa6-4.Whole_team.PNG new file mode 100644 index 000000000000..ff1dc284e265 Binary files /dev/null and b/theolive_versioned_docs/version-v1/assets/img/3030fa6-4.Whole_team.PNG differ diff --git a/theolive_versioned_docs/version-v1/assets/img/38e11d9-vmix-streaming-setting.PNG b/theolive_versioned_docs/version-v1/assets/img/38e11d9-vmix-streaming-setting.PNG new file mode 100644 index 000000000000..9aa7812f8666 Binary files /dev/null and b/theolive_versioned_docs/version-v1/assets/img/38e11d9-vmix-streaming-setting.PNG differ diff --git a/theolive_versioned_docs/version-v1/assets/img/3aad379-5.Personal_info.PNG b/theolive_versioned_docs/version-v1/assets/img/3aad379-5.Personal_info.PNG new file mode 100644 index 000000000000..b8fb1d99df8c Binary files /dev/null and b/theolive_versioned_docs/version-v1/assets/img/3aad379-5.Personal_info.PNG differ diff --git a/theolive_versioned_docs/version-v1/assets/img/3c77b57-channel-alias-analytics.png b/theolive_versioned_docs/version-v1/assets/img/3c77b57-channel-alias-analytics.png new file mode 100644 index 000000000000..55e3ff1c8e0a Binary files /dev/null and b/theolive_versioned_docs/version-v1/assets/img/3c77b57-channel-alias-analytics.png differ diff --git a/theolive_versioned_docs/version-v1/assets/img/42264c9-Wirecast_-_Detailed_Encoder_Settings.JPG b/theolive_versioned_docs/version-v1/assets/img/42264c9-Wirecast_-_Detailed_Encoder_Settings.JPG new file mode 100644 index 000000000000..88bb6fcfb95f Binary files /dev/null and b/theolive_versioned_docs/version-v1/assets/img/42264c9-Wirecast_-_Detailed_Encoder_Settings.JPG differ diff --git a/theolive_versioned_docs/version-v1/assets/img/447bd06-vmix1.png b/theolive_versioned_docs/version-v1/assets/img/447bd06-vmix1.png new file mode 100644 index 000000000000..dc6786105e67 Binary files /dev/null and b/theolive_versioned_docs/version-v1/assets/img/447bd06-vmix1.png differ diff --git a/theolive_versioned_docs/version-v1/assets/img/467abb8-overview.PNG b/theolive_versioned_docs/version-v1/assets/img/467abb8-overview.PNG new file mode 100644 index 000000000000..e80f355099b8 Binary files /dev/null and b/theolive_versioned_docs/version-v1/assets/img/467abb8-overview.PNG differ diff --git a/theolive_versioned_docs/version-v1/assets/img/48b69bf-Geoblocking.png b/theolive_versioned_docs/version-v1/assets/img/48b69bf-Geoblocking.png new file mode 100644 index 000000000000..7139d9fb9fbc Binary files /dev/null and b/theolive_versioned_docs/version-v1/assets/img/48b69bf-Geoblocking.png differ diff --git a/theolive_versioned_docs/version-v1/assets/img/48bc7d6-Wirecast_-_Encoding_Quality.png b/theolive_versioned_docs/version-v1/assets/img/48bc7d6-Wirecast_-_Encoding_Quality.png new file mode 100644 index 000000000000..ecf3567de839 Binary files /dev/null and b/theolive_versioned_docs/version-v1/assets/img/48bc7d6-Wirecast_-_Encoding_Quality.png differ diff --git a/theolive_versioned_docs/version-v1/assets/img/4f50555-settingsOBS.PNG b/theolive_versioned_docs/version-v1/assets/img/4f50555-settingsOBS.PNG new file mode 100644 index 000000000000..03be96dee7a7 Binary files /dev/null and b/theolive_versioned_docs/version-v1/assets/img/4f50555-settingsOBS.PNG differ diff --git a/theolive_versioned_docs/version-v1/assets/img/51376b6-token.png b/theolive_versioned_docs/version-v1/assets/img/51376b6-token.png new file mode 100644 index 000000000000..f360f88f5abf Binary files /dev/null and b/theolive_versioned_docs/version-v1/assets/img/51376b6-token.png differ diff --git a/theolive_versioned_docs/version-v1/assets/img/5361242-3.-THEOlive-console-token-list.PNG b/theolive_versioned_docs/version-v1/assets/img/5361242-3.-THEOlive-console-token-list.PNG new file mode 100644 index 000000000000..d8af4685a028 Binary files /dev/null and b/theolive_versioned_docs/version-v1/assets/img/5361242-3.-THEOlive-console-token-list.PNG differ diff --git a/theolive_versioned_docs/version-v1/assets/img/5513864-1.viewer_insights.PNG b/theolive_versioned_docs/version-v1/assets/img/5513864-1.viewer_insights.PNG new file mode 100644 index 000000000000..b5ed80567b98 Binary files /dev/null and b/theolive_versioned_docs/version-v1/assets/img/5513864-1.viewer_insights.PNG differ diff --git a/theolive_versioned_docs/version-v1/assets/img/567f3ad-console-section-customize.jpg b/theolive_versioned_docs/version-v1/assets/img/567f3ad-console-section-customize.jpg new file mode 100644 index 000000000000..a0f3b4ff7fe5 Binary files /dev/null and b/theolive_versioned_docs/version-v1/assets/img/567f3ad-console-section-customize.jpg differ diff --git a/theolive_versioned_docs/version-v1/assets/img/57e33f4-manage-webhook.PNG b/theolive_versioned_docs/version-v1/assets/img/57e33f4-manage-webhook.PNG new file mode 100644 index 000000000000..deb27fa6f276 Binary files /dev/null and b/theolive_versioned_docs/version-v1/assets/img/57e33f4-manage-webhook.PNG differ diff --git a/theolive_versioned_docs/version-v1/assets/img/5edb67a-OBS_snipping_1.PNG b/theolive_versioned_docs/version-v1/assets/img/5edb67a-OBS_snipping_1.PNG new file mode 100644 index 000000000000..2efbbdd66273 Binary files /dev/null and b/theolive_versioned_docs/version-v1/assets/img/5edb67a-OBS_snipping_1.PNG differ diff --git a/theolive_versioned_docs/version-v1/assets/img/6a57e61-channel-alias-include.png b/theolive_versioned_docs/version-v1/assets/img/6a57e61-channel-alias-include.png new file mode 100644 index 000000000000..7e85f12fe7e3 Binary files /dev/null and b/theolive_versioned_docs/version-v1/assets/img/6a57e61-channel-alias-include.png differ diff --git a/theolive_versioned_docs/version-v1/assets/img/71ca1fd-platform-panel1.png b/theolive_versioned_docs/version-v1/assets/img/71ca1fd-platform-panel1.png new file mode 100644 index 000000000000..c35701719c92 Binary files /dev/null and b/theolive_versioned_docs/version-v1/assets/img/71ca1fd-platform-panel1.png differ diff --git a/theolive_versioned_docs/version-v1/assets/img/73abc63-vmix3.png b/theolive_versioned_docs/version-v1/assets/img/73abc63-vmix3.png new file mode 100644 index 000000000000..cb14677ff46a Binary files /dev/null and b/theolive_versioned_docs/version-v1/assets/img/73abc63-vmix3.png differ diff --git a/theolive_versioned_docs/version-v1/assets/img/74289df-Postman_-_Landing_Page.JPG b/theolive_versioned_docs/version-v1/assets/img/74289df-Postman_-_Landing_Page.JPG new file mode 100644 index 000000000000..bd8b69b4affe Binary files /dev/null and b/theolive_versioned_docs/version-v1/assets/img/74289df-Postman_-_Landing_Page.JPG differ diff --git a/theolive_versioned_docs/version-v1/assets/img/74ca092-OBS_snipping_3.PNG b/theolive_versioned_docs/version-v1/assets/img/74ca092-OBS_snipping_3.PNG new file mode 100644 index 000000000000..d9d969f87c0f Binary files /dev/null and b/theolive_versioned_docs/version-v1/assets/img/74ca092-OBS_snipping_3.PNG differ diff --git a/theolive_versioned_docs/version-v1/assets/img/762eb40-colors.png b/theolive_versioned_docs/version-v1/assets/img/762eb40-colors.png new file mode 100644 index 000000000000..cad3987ff00b Binary files /dev/null and b/theolive_versioned_docs/version-v1/assets/img/762eb40-colors.png differ diff --git a/theolive_versioned_docs/version-v1/assets/img/76aaff1-3.Add-credit-or-debit-card.PNG b/theolive_versioned_docs/version-v1/assets/img/76aaff1-3.Add-credit-or-debit-card.PNG new file mode 100644 index 000000000000..8c6b8caac73e Binary files /dev/null and b/theolive_versioned_docs/version-v1/assets/img/76aaff1-3.Add-credit-or-debit-card.PNG differ diff --git a/theolive_versioned_docs/version-v1/assets/img/7918a6d-viewer-panel.png b/theolive_versioned_docs/version-v1/assets/img/7918a6d-viewer-panel.png new file mode 100644 index 000000000000..b602d16f9176 Binary files /dev/null and b/theolive_versioned_docs/version-v1/assets/img/7918a6d-viewer-panel.png differ diff --git a/theolive_versioned_docs/version-v1/assets/img/7b3faa5-Wirecast_-_Select_Source.jpg b/theolive_versioned_docs/version-v1/assets/img/7b3faa5-Wirecast_-_Select_Source.jpg new file mode 100644 index 000000000000..b2ac92ba91a6 Binary files /dev/null and b/theolive_versioned_docs/version-v1/assets/img/7b3faa5-Wirecast_-_Select_Source.jpg differ diff --git a/theolive_versioned_docs/version-v1/assets/img/7fc1245-small-size.PNG b/theolive_versioned_docs/version-v1/assets/img/7fc1245-small-size.PNG new file mode 100644 index 000000000000..642f00288710 Binary files /dev/null and b/theolive_versioned_docs/version-v1/assets/img/7fc1245-small-size.PNG differ diff --git a/theolive_versioned_docs/version-v1/assets/img/834fd73-waiting-example.PNG b/theolive_versioned_docs/version-v1/assets/img/834fd73-waiting-example.PNG new file mode 100644 index 000000000000..26ff3de46e6b Binary files /dev/null and b/theolive_versioned_docs/version-v1/assets/img/834fd73-waiting-example.PNG differ diff --git a/theolive_versioned_docs/version-v1/assets/img/8751d4a-alias-settings.PNG b/theolive_versioned_docs/version-v1/assets/img/8751d4a-alias-settings.PNG new file mode 100644 index 000000000000..2c2a50176b27 Binary files /dev/null and b/theolive_versioned_docs/version-v1/assets/img/8751d4a-alias-settings.PNG differ diff --git a/theolive_versioned_docs/version-v1/assets/img/8ce9112-create-scheduler.PNG b/theolive_versioned_docs/version-v1/assets/img/8ce9112-create-scheduler.PNG new file mode 100644 index 000000000000..680323105a20 Binary files /dev/null and b/theolive_versioned_docs/version-v1/assets/img/8ce9112-create-scheduler.PNG differ diff --git a/theolive_versioned_docs/version-v1/assets/img/8d77256-Screenshot_2023-06-28_131652.png b/theolive_versioned_docs/version-v1/assets/img/8d77256-Screenshot_2023-06-28_131652.png new file mode 100644 index 000000000000..163cb1908e4a Binary files /dev/null and b/theolive_versioned_docs/version-v1/assets/img/8d77256-Screenshot_2023-06-28_131652.png differ diff --git a/theolive_versioned_docs/version-v1/assets/img/8e7abe9-2.Billing-details-fields-overview.PNG b/theolive_versioned_docs/version-v1/assets/img/8e7abe9-2.Billing-details-fields-overview.PNG new file mode 100644 index 000000000000..9ed057372939 Binary files /dev/null and b/theolive_versioned_docs/version-v1/assets/img/8e7abe9-2.Billing-details-fields-overview.PNG differ diff --git a/theolive_versioned_docs/version-v1/assets/img/94e8600-Wirecast_-_Output_Destination.JPG b/theolive_versioned_docs/version-v1/assets/img/94e8600-Wirecast_-_Output_Destination.JPG new file mode 100644 index 000000000000..c878d19ba930 Binary files /dev/null and b/theolive_versioned_docs/version-v1/assets/img/94e8600-Wirecast_-_Output_Destination.JPG differ diff --git a/theolive_versioned_docs/version-v1/assets/img/9ce6eb8-Create_channel_alias.jpg b/theolive_versioned_docs/version-v1/assets/img/9ce6eb8-Create_channel_alias.jpg new file mode 100644 index 000000000000..ea2bf6b7c236 Binary files /dev/null and b/theolive_versioned_docs/version-v1/assets/img/9ce6eb8-Create_channel_alias.jpg differ diff --git a/theolive_versioned_docs/version-v1/assets/img/a1acade-create-webhook.PNG b/theolive_versioned_docs/version-v1/assets/img/a1acade-create-webhook.PNG new file mode 100644 index 000000000000..65c112dffc72 Binary files /dev/null and b/theolive_versioned_docs/version-v1/assets/img/a1acade-create-webhook.PNG differ diff --git a/theolive_versioned_docs/version-v1/assets/img/a24f145-geoblock.PNG b/theolive_versioned_docs/version-v1/assets/img/a24f145-geoblock.PNG new file mode 100644 index 000000000000..445fdf6afdc7 Binary files /dev/null and b/theolive_versioned_docs/version-v1/assets/img/a24f145-geoblock.PNG differ diff --git a/theolive_versioned_docs/version-v1/assets/img/a688033-OBS_snipping_2.PNG b/theolive_versioned_docs/version-v1/assets/img/a688033-OBS_snipping_2.PNG new file mode 100644 index 000000000000..43618512368a Binary files /dev/null and b/theolive_versioned_docs/version-v1/assets/img/a688033-OBS_snipping_2.PNG differ diff --git a/theolive_versioned_docs/version-v1/assets/img/b212f75-Wirecast_-_RTMPurl__Streamkey.jpg b/theolive_versioned_docs/version-v1/assets/img/b212f75-Wirecast_-_RTMPurl__Streamkey.jpg new file mode 100644 index 000000000000..bcd50af28d9e Binary files /dev/null and b/theolive_versioned_docs/version-v1/assets/img/b212f75-Wirecast_-_RTMPurl__Streamkey.jpg differ diff --git a/theolive_versioned_docs/version-v1/assets/img/b4945ca-Wirecast_-_Activate_Layer.jpg b/theolive_versioned_docs/version-v1/assets/img/b4945ca-Wirecast_-_Activate_Layer.jpg new file mode 100644 index 000000000000..c45784d6c05b Binary files /dev/null and b/theolive_versioned_docs/version-v1/assets/img/b4945ca-Wirecast_-_Activate_Layer.jpg differ diff --git a/theolive_versioned_docs/version-v1/assets/img/b636bf5-create-channel.PNG b/theolive_versioned_docs/version-v1/assets/img/b636bf5-create-channel.PNG new file mode 100644 index 000000000000..5cc2fa997484 Binary files /dev/null and b/theolive_versioned_docs/version-v1/assets/img/b636bf5-create-channel.PNG differ diff --git a/theolive_versioned_docs/version-v1/assets/img/bb9b4a6-2.-THEOlive-console-generated-token-and-secret.PNG b/theolive_versioned_docs/version-v1/assets/img/bb9b4a6-2.-THEOlive-console-generated-token-and-secret.PNG new file mode 100644 index 000000000000..002bc285d7f7 Binary files /dev/null and b/theolive_versioned_docs/version-v1/assets/img/bb9b4a6-2.-THEOlive-console-generated-token-and-secret.PNG differ diff --git a/theolive_versioned_docs/version-v1/assets/img/bcb0dde-vmix0.png b/theolive_versioned_docs/version-v1/assets/img/bcb0dde-vmix0.png new file mode 100644 index 000000000000..93095df85dbd Binary files /dev/null and b/theolive_versioned_docs/version-v1/assets/img/bcb0dde-vmix0.png differ diff --git a/theolive_versioned_docs/version-v1/assets/img/c0aca77-1.-THEOlive-console-generate-token.PNG b/theolive_versioned_docs/version-v1/assets/img/c0aca77-1.-THEOlive-console-generate-token.PNG new file mode 100644 index 000000000000..c454c3f876f7 Binary files /dev/null and b/theolive_versioned_docs/version-v1/assets/img/c0aca77-1.-THEOlive-console-generate-token.PNG differ diff --git a/theolive_versioned_docs/version-v1/assets/img/cbe288c-start.PNG b/theolive_versioned_docs/version-v1/assets/img/cbe288c-start.PNG new file mode 100644 index 000000000000..e7ec7b5a644f Binary files /dev/null and b/theolive_versioned_docs/version-v1/assets/img/cbe288c-start.PNG differ diff --git a/theolive_versioned_docs/version-v1/assets/img/cd5c594-scheduler-overview.png b/theolive_versioned_docs/version-v1/assets/img/cd5c594-scheduler-overview.png new file mode 100644 index 000000000000..fa60994a6a2e Binary files /dev/null and b/theolive_versioned_docs/version-v1/assets/img/cd5c594-scheduler-overview.png differ diff --git a/theolive_versioned_docs/version-v1/assets/img/consolechannelstart.png b/theolive_versioned_docs/version-v1/assets/img/consolechannelstart.png new file mode 100644 index 000000000000..3818548b0190 Binary files /dev/null and b/theolive_versioned_docs/version-v1/assets/img/consolechannelstart.png differ diff --git a/theolive_versioned_docs/version-v1/assets/img/d2e680e-webhooks.png b/theolive_versioned_docs/version-v1/assets/img/d2e680e-webhooks.png new file mode 100644 index 000000000000..533070fd8548 Binary files /dev/null and b/theolive_versioned_docs/version-v1/assets/img/d2e680e-webhooks.png differ diff --git a/theolive_versioned_docs/version-v1/assets/img/d72c440-3.-create-channel.PNG b/theolive_versioned_docs/version-v1/assets/img/d72c440-3.-create-channel.PNG new file mode 100644 index 000000000000..99c5192a54c1 Binary files /dev/null and b/theolive_versioned_docs/version-v1/assets/img/d72c440-3.-create-channel.PNG differ diff --git a/theolive_versioned_docs/version-v1/assets/img/dcb32a2-billing-details.PNG b/theolive_versioned_docs/version-v1/assets/img/dcb32a2-billing-details.PNG new file mode 100644 index 000000000000..151af36b1b8c Binary files /dev/null and b/theolive_versioned_docs/version-v1/assets/img/dcb32a2-billing-details.PNG differ diff --git a/theolive_versioned_docs/version-v1/assets/img/dcdfc37-token_security.png b/theolive_versioned_docs/version-v1/assets/img/dcdfc37-token_security.png new file mode 100644 index 000000000000..b530a6dd4805 Binary files /dev/null and b/theolive_versioned_docs/version-v1/assets/img/dcdfc37-token_security.png differ diff --git a/theolive_versioned_docs/version-v1/assets/img/e35aec9-2.Team.PNG b/theolive_versioned_docs/version-v1/assets/img/e35aec9-2.Team.PNG new file mode 100644 index 000000000000..0a1426719fda Binary files /dev/null and b/theolive_versioned_docs/version-v1/assets/img/e35aec9-2.Team.PNG differ diff --git a/theolive_versioned_docs/version-v1/assets/img/e409065-where-insights3.PNG b/theolive_versioned_docs/version-v1/assets/img/e409065-where-insights3.PNG new file mode 100644 index 000000000000..e50328ea48c9 Binary files /dev/null and b/theolive_versioned_docs/version-v1/assets/img/e409065-where-insights3.PNG differ diff --git a/theolive_versioned_docs/version-v1/assets/img/e631989-latency-panel2.png b/theolive_versioned_docs/version-v1/assets/img/e631989-latency-panel2.png new file mode 100644 index 000000000000..faa5382605a8 Binary files /dev/null and b/theolive_versioned_docs/version-v1/assets/img/e631989-latency-panel2.png differ diff --git a/theolive_versioned_docs/version-v1/assets/img/f033f01-2.-auth.png b/theolive_versioned_docs/version-v1/assets/img/f033f01-2.-auth.png new file mode 100644 index 000000000000..2add2620a54d Binary files /dev/null and b/theolive_versioned_docs/version-v1/assets/img/f033f01-2.-auth.png differ diff --git a/theolive_versioned_docs/version-v1/assets/img/f1499d0-big-size.PNG b/theolive_versioned_docs/version-v1/assets/img/f1499d0-big-size.PNG new file mode 100644 index 000000000000..f0064d9ccecd Binary files /dev/null and b/theolive_versioned_docs/version-v1/assets/img/f1499d0-big-size.PNG differ diff --git a/theolive_versioned_docs/version-v1/assets/img/fae9921-streaming-quality-settings.jpg b/theolive_versioned_docs/version-v1/assets/img/fae9921-streaming-quality-settings.jpg new file mode 100644 index 000000000000..294c786527f9 Binary files /dev/null and b/theolive_versioned_docs/version-v1/assets/img/fae9921-streaming-quality-settings.jpg differ diff --git a/theolive_versioned_docs/version-v1/assets/img/fe6b54f-3._New_user.jpg b/theolive_versioned_docs/version-v1/assets/img/fe6b54f-3._New_user.jpg new file mode 100644 index 000000000000..ce894811b05b Binary files /dev/null and b/theolive_versioned_docs/version-v1/assets/img/fe6b54f-3._New_user.jpg differ diff --git a/theolive_versioned_docs/version-v1/assets/img/fea4c5a-Wirecast_-_New_Layer.JPG b/theolive_versioned_docs/version-v1/assets/img/fea4c5a-Wirecast_-_New_Layer.JPG new file mode 100644 index 000000000000..7b1699652c87 Binary files /dev/null and b/theolive_versioned_docs/version-v1/assets/img/fea4c5a-Wirecast_-_New_Layer.JPG differ diff --git a/theolive_versioned_docs/version-v1/assets/img/geoblockconsole.png b/theolive_versioned_docs/version-v1/assets/img/geoblockconsole.png new file mode 100644 index 000000000000..c64359ec5973 Binary files /dev/null and b/theolive_versioned_docs/version-v1/assets/img/geoblockconsole.png differ diff --git a/theolive_versioned_docs/version-v1/assets/img/hardware-encoders/Videon_Edgecaster_-_Audio_Profile.jpg b/theolive_versioned_docs/version-v1/assets/img/hardware-encoders/Videon_Edgecaster_-_Audio_Profile.jpg new file mode 100644 index 000000000000..f522433c3405 Binary files /dev/null and b/theolive_versioned_docs/version-v1/assets/img/hardware-encoders/Videon_Edgecaster_-_Audio_Profile.jpg differ diff --git a/theolive_versioned_docs/version-v1/assets/img/hardware-encoders/Videon_Edgecaster_-_Input_Settings.jpg b/theolive_versioned_docs/version-v1/assets/img/hardware-encoders/Videon_Edgecaster_-_Input_Settings.jpg new file mode 100644 index 000000000000..8d8c3edd9159 Binary files /dev/null and b/theolive_versioned_docs/version-v1/assets/img/hardware-encoders/Videon_Edgecaster_-_Input_Settings.jpg differ diff --git a/theolive_versioned_docs/version-v1/assets/img/hardware-encoders/Videon_Edgecaster_-_Output.jpg b/theolive_versioned_docs/version-v1/assets/img/hardware-encoders/Videon_Edgecaster_-_Output.jpg new file mode 100644 index 000000000000..2ea0674e7553 Binary files /dev/null and b/theolive_versioned_docs/version-v1/assets/img/hardware-encoders/Videon_Edgecaster_-_Output.jpg differ diff --git a/theolive_versioned_docs/version-v1/assets/img/hardware-encoders/Videon_Edgecaster_-_Video_Profile.jpg b/theolive_versioned_docs/version-v1/assets/img/hardware-encoders/Videon_Edgecaster_-_Video_Profile.jpg new file mode 100644 index 000000000000..052f5b58c0c9 Binary files /dev/null and b/theolive_versioned_docs/version-v1/assets/img/hardware-encoders/Videon_Edgecaster_-_Video_Profile.jpg differ diff --git a/theolive_versioned_docs/version-v1/assets/img/hardware-encoders/haivision_logo.jpeg b/theolive_versioned_docs/version-v1/assets/img/hardware-encoders/haivision_logo.jpeg new file mode 100644 index 000000000000..0048de505264 Binary files /dev/null and b/theolive_versioned_docs/version-v1/assets/img/hardware-encoders/haivision_logo.jpeg differ diff --git a/theolive_versioned_docs/version-v1/assets/img/hardware-encoders/magewell-connect-stream.png b/theolive_versioned_docs/version-v1/assets/img/hardware-encoders/magewell-connect-stream.png new file mode 100644 index 000000000000..92b32cc2dd8c Binary files /dev/null and b/theolive_versioned_docs/version-v1/assets/img/hardware-encoders/magewell-connect-stream.png differ diff --git a/theolive_versioned_docs/version-v1/assets/img/hardware-encoders/magewell-connect.png b/theolive_versioned_docs/version-v1/assets/img/hardware-encoders/magewell-connect.png new file mode 100644 index 000000000000..8cdbcedc7f91 Binary files /dev/null and b/theolive_versioned_docs/version-v1/assets/img/hardware-encoders/magewell-connect.png differ diff --git a/theolive_versioned_docs/version-v1/assets/img/hardware-encoders/magewell-rtmp-live.png b/theolive_versioned_docs/version-v1/assets/img/hardware-encoders/magewell-rtmp-live.png new file mode 100644 index 000000000000..e0b61522587e Binary files /dev/null and b/theolive_versioned_docs/version-v1/assets/img/hardware-encoders/magewell-rtmp-live.png differ diff --git a/theolive_versioned_docs/version-v1/assets/img/hardware-encoders/magewell-rtmp.png b/theolive_versioned_docs/version-v1/assets/img/hardware-encoders/magewell-rtmp.png new file mode 100644 index 000000000000..2790d9aace3a Binary files /dev/null and b/theolive_versioned_docs/version-v1/assets/img/hardware-encoders/magewell-rtmp.png differ diff --git a/theolive_versioned_docs/version-v1/assets/img/hardware-encoders/magewell_logo.jpeg b/theolive_versioned_docs/version-v1/assets/img/hardware-encoders/magewell_logo.jpeg new file mode 100644 index 000000000000..fc907455b9fc Binary files /dev/null and b/theolive_versioned_docs/version-v1/assets/img/hardware-encoders/magewell_logo.jpeg differ diff --git a/theolive_versioned_docs/version-v1/assets/img/hardware-encoders/osprey-login.jpeg b/theolive_versioned_docs/version-v1/assets/img/hardware-encoders/osprey-login.jpeg new file mode 100644 index 000000000000..fd0e459feb70 Binary files /dev/null and b/theolive_versioned_docs/version-v1/assets/img/hardware-encoders/osprey-login.jpeg differ diff --git a/theolive_versioned_docs/version-v1/assets/img/hardware-encoders/osprey-rtmp-live.png b/theolive_versioned_docs/version-v1/assets/img/hardware-encoders/osprey-rtmp-live.png new file mode 100644 index 000000000000..25cc29827ad6 Binary files /dev/null and b/theolive_versioned_docs/version-v1/assets/img/hardware-encoders/osprey-rtmp-live.png differ diff --git a/theolive_versioned_docs/version-v1/assets/img/hardware-encoders/osprey-talon.jpg b/theolive_versioned_docs/version-v1/assets/img/hardware-encoders/osprey-talon.jpg new file mode 100644 index 000000000000..1818457fdf3e Binary files /dev/null and b/theolive_versioned_docs/version-v1/assets/img/hardware-encoders/osprey-talon.jpg differ diff --git a/theolive_versioned_docs/version-v1/assets/img/hardware-encoders/osprey_logo.jpeg b/theolive_versioned_docs/version-v1/assets/img/hardware-encoders/osprey_logo.jpeg new file mode 100644 index 000000000000..2737b41568df Binary files /dev/null and b/theolive_versioned_docs/version-v1/assets/img/hardware-encoders/osprey_logo.jpeg differ diff --git a/theolive_versioned_docs/version-v1/assets/img/hardware-encoders/theolive-ingest-server-rtmp-push.png b/theolive_versioned_docs/version-v1/assets/img/hardware-encoders/theolive-ingest-server-rtmp-push.png new file mode 100644 index 000000000000..e2c137798def Binary files /dev/null and b/theolive_versioned_docs/version-v1/assets/img/hardware-encoders/theolive-ingest-server-rtmp-push.png differ diff --git a/theolive_versioned_docs/version-v1/assets/img/hardware-encoders/videon_central_logo.jpeg b/theolive_versioned_docs/version-v1/assets/img/hardware-encoders/videon_central_logo.jpeg new file mode 100644 index 000000000000..c2ced584e060 Binary files /dev/null and b/theolive_versioned_docs/version-v1/assets/img/hardware-encoders/videon_central_logo.jpeg differ diff --git a/theolive_versioned_docs/version-v1/assets/img/ipblockconsole.png b/theolive_versioned_docs/version-v1/assets/img/ipblockconsole.png new file mode 100644 index 000000000000..47c24a7b116d Binary files /dev/null and b/theolive_versioned_docs/version-v1/assets/img/ipblockconsole.png differ diff --git a/theolive_versioned_docs/version-v1/assets/img/obsfps.png b/theolive_versioned_docs/version-v1/assets/img/obsfps.png new file mode 100644 index 000000000000..b5d5d909ebc2 Binary files /dev/null and b/theolive_versioned_docs/version-v1/assets/img/obsfps.png differ diff --git a/theolive_versioned_docs/version-v1/assets/img/obsoutput.png b/theolive_versioned_docs/version-v1/assets/img/obsoutput.png new file mode 100644 index 000000000000..d2803f0a0eb0 Binary files /dev/null and b/theolive_versioned_docs/version-v1/assets/img/obsoutput.png differ diff --git a/theolive_versioned_docs/version-v1/assets/img/obsoutputsettings.png b/theolive_versioned_docs/version-v1/assets/img/obsoutputsettings.png new file mode 100644 index 000000000000..9dd28b467ebd Binary files /dev/null and b/theolive_versioned_docs/version-v1/assets/img/obsoutputsettings.png differ diff --git a/theolive_versioned_docs/version-v1/assets/img/obssource.png b/theolive_versioned_docs/version-v1/assets/img/obssource.png new file mode 100644 index 000000000000..d65087b1c0cd Binary files /dev/null and b/theolive_versioned_docs/version-v1/assets/img/obssource.png differ diff --git a/theolive_versioned_docs/version-v1/assets/img/obsstartstreaming.png b/theolive_versioned_docs/version-v1/assets/img/obsstartstreaming.png new file mode 100644 index 000000000000..dade0f7c422d Binary files /dev/null and b/theolive_versioned_docs/version-v1/assets/img/obsstartstreaming.png differ diff --git a/theolive_versioned_docs/version-v1/assets/img/srt-multi-audio.png b/theolive_versioned_docs/version-v1/assets/img/srt-multi-audio.png new file mode 100644 index 000000000000..5ae6e8719b3d Binary files /dev/null and b/theolive_versioned_docs/version-v1/assets/img/srt-multi-audio.png differ diff --git a/theolive_versioned_docs/version-v1/assets/img/theolive-license.png b/theolive_versioned_docs/version-v1/assets/img/theolive-license.png new file mode 100644 index 000000000000..ca38e5f39c11 Binary files /dev/null and b/theolive_versioned_docs/version-v1/assets/img/theolive-license.png differ diff --git a/theolive_versioned_docs/version-v1/callouts/_premium_feature.md b/theolive_versioned_docs/version-v1/callouts/_premium_feature.md new file mode 100644 index 000000000000..f2e806e1f0fc --- /dev/null +++ b/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. + +::: diff --git a/theolive_versioned_docs/version-v1/contribution/hardware-encoders/_category_.json b/theolive_versioned_docs/version-v1/contribution/hardware-encoders/_category_.json new file mode 100644 index 000000000000..e7749d13ce2f --- /dev/null +++ b/theolive_versioned_docs/version-v1/contribution/hardware-encoders/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Hardware Encoders", + "position": 4 +} diff --git a/theolive_versioned_docs/version-v1/contribution/hardware-encoders/haivision.mdx b/theolive_versioned_docs/version-v1/contribution/hardware-encoders/haivision.mdx new file mode 100644 index 000000000000..f1826e1550c1 --- /dev/null +++ b/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..hesp.live/live` +4. Enter the RTMP publish stream name from the ingest server section. + Stream Name: `` + +import RtmpPush from '../../assets/img/hardware-encoders/theolive-ingest-server-rtmp-push.png'; + +
+ +
+ +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. +::: diff --git a/theolive_versioned_docs/version-v1/contribution/hardware-encoders/index.mdx b/theolive_versioned_docs/version-v1/contribution/hardware-encoders/index.mdx new file mode 100644 index 000000000000..8be08c8fce88 --- /dev/null +++ b/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'; + + + [![Haivision](../../assets/img/hardware-encoders/haivision_logo.jpeg)](haivision.mdx) + [![Magewell](../../assets/img/hardware-encoders/magewell_logo.jpeg)](magewell.mdx) + [![Osprey](../../assets/img/hardware-encoders/osprey_logo.jpeg)](osprey.mdx) + [![Videon](../../assets/img/hardware-encoders/videon_central_logo.jpeg)](videon.mdx) + + +### 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. diff --git a/theolive_versioned_docs/version-v1/contribution/hardware-encoders/magewell.mdx b/theolive_versioned_docs/version-v1/contribution/hardware-encoders/magewell.mdx new file mode 100644 index 000000000000..a8fa2efebc9a --- /dev/null +++ b/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'; + +
+ +
+ +- For the `URL` select `rtmps://` and enter the **URL** of the channel. + RTMP URL: `rtmps://rtmp..hesp.live/live` +- For the `Stream key` input the **Stream key** from the ingest server section. + 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'; + +
+ +
+ +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'; + +
+ +
+ +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'; + +
+ +
diff --git a/theolive_versioned_docs/version-v1/contribution/hardware-encoders/osprey.mdx b/theolive_versioned_docs/version-v1/contribution/hardware-encoders/osprey.mdx new file mode 100644 index 000000000000..2713cb0af0b1 --- /dev/null +++ b/theolive_versioned_docs/version-v1/contribution/hardware-encoders/osprey.mdx @@ -0,0 +1,47 @@ +--- +title: Osprey +slug: /hardware-encoders/osprey +--- + +**Osprey Video** is a world leader in broadcasting solutions and an early adopter of [WHIP](/millicast/broadcast/webrtc-and-whip) for their Osprey Talon 4K-SC Encoder. + +See the official [Osprey Video](https://www.ospreyvideo.com/) site for documentation, installation instructions, and additional support. + +## Osprey Talon + +You'll need to plug an ethernet connection and a power supply into your Talon encoder and power the device on. + +import OspreyTalon2 from '../../assets/img/hardware-encoders/osprey-talon.jpg'; + +
+ +
+ +### Connect to the encoder + +Once powered on, the device will be discoverable on your local network. You can interface with the device by opening the IP address in your browser, or, if you are a Windows user, you can [download the Osprey Boss Pro](https://www.ospreyvideo.com/talon-software-and-firmware), which provides a UI for finding the encoder. + +Once found in your browser, you'll be prompted to log into the device. Refer to the [Osprey Talon Encoder User Manual ](https://www.ospreyvideo.com/manuals)to learn about your device's username and password. + +import OspreyTalon3 from '../../assets/img/hardware-encoders/osprey-login.jpeg'; + +
+ +
+ +### Configure RTMP settings + +Inside the encoder UI, click on the _Channels_ tab. From the Channels tab, set the protocol to **RTMP/RTMPS**. + +- For the `Destination` copy the RTMP publish path from the Dolby _channel_ you have created. + RTMP URL: `rtmps://rtmp..hesp.live/live` +- For the `Stream Key` input RTMP publish stream name from the ingest server section. + Stream Name: `` + +import OspreyTalon4 from '../../assets/img/hardware-encoders/osprey-rtmp-live.png'; + +
+ +
+ +Once configured, you can press start and the encoder will begin streaming content. diff --git a/theolive_versioned_docs/version-v1/contribution/hardware-encoders/videon.mdx b/theolive_versioned_docs/version-v1/contribution/hardware-encoders/videon.mdx new file mode 100644 index 000000000000..c1542d8bad67 --- /dev/null +++ b/theolive_versioned_docs/version-v1/contribution/hardware-encoders/videon.mdx @@ -0,0 +1,67 @@ +--- +title: Videon +slug: /hardware-encoders/videon +--- + +**Videon** is a leading video streaming company offering innovative solutions to enhance content delivery and quality. Their flagship product, [EdgeCaster](https://www.videonlabs.com/edgecaster), optimizes video streaming with low-latency and high-quality playback across platforms, empowering service providers to deliver seamless and engaging viewing experiences. + +See the official [VideonLabs](https://www.videonlabs.com/) site for documentation, installation instructions, and additional support. + +## 1. Input settings + +In your Videon EdgeCaster Streaming Dashboard configure the following settings: + +- Under the "AV Input" section, please select "Input Settings". +- Select your Video Input (SDI/HDMI) and Audio Input audio (Embedded Audio/3.5mm Audio). The "Video Input Resolution" will automatically be detected. In the example below this is 1080p25. +- Click on the "Save" button. + +import RtmpPush from '../../assets/img/hardware-encoders/Videon_Edgecaster_-_Input_Settings.jpg'; + +
+ Defining the input settings +
+ +:::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. +::: + +## 2. Set your Video Profile + +- Under the "Video Profiles" section, please select your profile, or create a new one. In the example below we have selected the profile "hesp.live". If you would create a new profile, you can change the name by clicking on the pencil. +- Under Video Scaling, select the desired resolution. Note that THEOlive support resolutions up to 1080p. The resolution of your ingested stream can be found under "Encoded Video Resolution". In the example below we have selected pass through, which means we keep our "Encoded Video Resolution" of 1080p25. +- Match the "Video bitrate" value to the maximum value of the channel preset you are using. See [Stream configuration](../stream-configuration.mdx) for more details. +- Further configure your encoding settings. Select `Lowest`, `Low`, `Normal` or `High` in the Quality/Latency drop-down menu, depending on your preference. Selecting `Lowest` will give you lower quality but also the lowest latency and the other way around for `High` which gives the `Highest` quality but with slightly higher latency. +- Click on the "Save" button. + +import VideoProfile from '../../assets/img/hardware-encoders/Videon_Edgecaster_-_Video_Profile.jpg'; + +
+ Setting up the video profile +
+ +## 3. Set your Audio profile + +- Under the "Audio Profiles" section, please select your profile, or create a new one. In the example below we have selected the profile "hesp.live". If you would create a new profile, you can change the name by clicking on the pencil. +- Select your audio encoding settings. In the example below ´MPEG-4 AAC-LC\` has been selected with 128kbps audio bitrate. +- Click on the "Save" button. + +import AudioProfile from '../../assets/img/hardware-encoders/Videon_Edgecaster_-_Audio_Profile.jpg'; + +
+ Setting up the video profile +
+ +## 4. Setting the Outputs + +- Under the Section "Outputs", select an RTMP output. ´RTMP 1´ has been selected in the example below. +- Select the "Video Source" and "Audio Source" previously defined under sections 2 and 3. +- Select `Genetic RTMP` under the "Streaming Providers" dropdown menu. +- Use your RTMP Push URL and stream key to complete the "Stream URL". The stream key should be copied after the RTMP Push URL. So if your RTMP Push URL is `rtmps://rtmp..theo.live/live` and your stream key ``, then you should complete after the "rtmps://" `rtmp..theo.live/live/` +- Click on the "Save" button. +- You are now ready to start streaming! Switch on the "Output" by moving the orange button to "On". + +import EdgecasterOutput from '../../assets/img/hardware-encoders/Videon_Edgecaster_-_Output.jpg'; + +
+ Setting the outputs +
diff --git a/theolive_versioned_docs/version-v1/contribution/multi-audio-support.mdx b/theolive_versioned_docs/version-v1/contribution/multi-audio-support.mdx new file mode 100644 index 000000000000..b928e92a6502 --- /dev/null +++ b/theolive_versioned_docs/version-v1/contribution/multi-audio-support.mdx @@ -0,0 +1,46 @@ +--- +sidebar_position: 2 +sidebar_label: Multi-audio support +--- + +# Multi-audio support + +--- + +The Dolby OptiView platform supports multi-audio ingest and delivery with our HESP solution. This functionality is perfect for +use cases such as live events where multiple languages or commentary may be required. + +:::caution +This functionality is **only** supported through the SRT Pull ingest method. Playback is **only** supported on web. +::: + +## Configuring multi-audio ingest and playback + +To deliver multi audio SRT the following steps must be taken: + +1. Within your dashboard configure your SRT listener endpoint. +2. Configure your expected incoming "Audio tracks" by specifying a language, label, and the expected PID. + +
![SRT Multi-audio example with PIDs](../assets/img/srt-multi-audio.png)
+ +3. Start the Channel and begin ingesting video and audio into the engine. +4. Your output will be available for playback on web only via the [channel alias](../platform/multi-channel.md). +5. You can validate the audio tracks are being delivered via the demo player : `https://demo.theo.live/?channel=YOUR_CHANNEL_ID` + +## Feature Compatibility and Limitations + +- Audio must be encoded as AAC. +- Only stereo audio is supported. +- There is a limit of 12 audio tracks per channel. + +#### Ingest + +| RTMP Push | RTMP Pull | SRT Pull | +| :-------: | :-------: | :------: | +| No | No | Yes | + +#### Playback + +| Web SDK | Android SDK | iOS SDK | +| :-----: | :---------: | :-----: | +| Yes | No | No | diff --git a/theolive_versioned_docs/version-v1/contribution/sei-messages.mdx b/theolive_versioned_docs/version-v1/contribution/sei-messages.mdx new file mode 100644 index 000000000000..5dc06cf4afe3 --- /dev/null +++ b/theolive_versioned_docs/version-v1/contribution/sei-messages.mdx @@ -0,0 +1,14 @@ +--- +sidebar_position: 3 +sidebar_label: In-stream Metadata +--- + +# In-stream metadata through SEI messages + +--- + +THEOlive allows you to embed metadata into your stream that is preserved throughout the THEOlive pipeline and can be accessed by the player. + +The first step is adding the metadata to your (h264) input stream in the form of picture timing SEI messages as defined in ITUT H264 Annex D 1.3. These messages allow you to add a timestamp to your frames and associate the timestamp with an event that happened on your backend. + +The next step is [listening to these messages in the player](../playback/web/metadata.mdx). diff --git a/theolive_versioned_docs/version-v1/contribution/software-encoders/_category_.json b/theolive_versioned_docs/version-v1/contribution/software-encoders/_category_.json new file mode 100644 index 000000000000..59985b1d833f --- /dev/null +++ b/theolive_versioned_docs/version-v1/contribution/software-encoders/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Software Encoders", + "position": 5 +} diff --git a/theolive_versioned_docs/version-v1/contribution/software-encoders/ffmpeg.md b/theolive_versioned_docs/version-v1/contribution/software-encoders/ffmpeg.md new file mode 100644 index 000000000000..c5b875cbfa2c --- /dev/null +++ b/theolive_versioned_docs/version-v1/contribution/software-encoders/ffmpeg.md @@ -0,0 +1,58 @@ +--- +sidebar_position: 6 +sidebar_label: FFmpeg +--- + +# Using FFmpeg with THEOlive + +**FFmpeg** is a free open-source software project with command-line tools for handling video, audio, and other multimedia. It is common practice to use Ffmpeg in production workflows when broadcasting from a media file on disk. + +Broadcasts are started using the `ffmpeg` command-line to forward a source using RTMP broadcast contribution protocol to stream content to THEOlive. + +See the official [ffmpeg.org](https://ffmpeg.org/) documentation for installation instructions and additional support. + +## Common Settings + +| Parameter | Description | +| :----------------- | :----------------------------------------------- | +| \-stream_loop -1 | Loop the video indefinitely | +| \-vb 4500k | Video Bitrate setting of 4.5 Mbps | +| \-c:a copy | Copy the audio codec from the input | +| \-bf 0 | Disable bframes | +| \-g 60 | Group of pictures (GOP) size | +| \-f flv | Package flash video | +| \-preset veryfast | Video encoding speed to compression ratio preset | +| \-tune zerolatency | Good for fast encoding and low-latency streaming | +| \-vprofile main | H264 video profile | + +:::warning -re flag +Do not use the `-re` flag when the input is an actual capture device or a live stream as it may cause packet loss and higher latency. +::: + +## Start the stream + +Run the following command with the proper settings in order to start publishing to your channel. + +```shell +MEDIA_FILE="/path/to/file.mp4" +RTMP_PUBLISH_URL="rtmps://rtmp..theo.live/live" +RTMP_STREAM_KEY="Your stream key" + +ffmpeg -re -stream_loop -1 -i $VIDEO_FILE_PATH \ + -vcodec libx264 \ + -preset veryfast \ + -bf 0 \ + -g 60 \ + -vb 4500k \ + -vprofile main \ + -tune zerolatency \ + -level 3.0 \ + -c:a copy \ + -f flv \ + -rtmp_playpath $RTMP_STREAM_KEY \ + -rtmp_live live $RTMP_PUBLISH_URL +``` + +:::info Upload bandwidth +Make sure that your encoder has a stable connection and enough upload bandwidth. This will ensure all data is correctly sent to the THEOlive channel. +::: diff --git a/theolive_versioned_docs/version-v1/contribution/software-encoders/index.mdx b/theolive_versioned_docs/version-v1/contribution/software-encoders/index.mdx new file mode 100644 index 000000000000..7a30cdca4c19 --- /dev/null +++ b/theolive_versioned_docs/version-v1/contribution/software-encoders/index.mdx @@ -0,0 +1,39 @@ +--- +title: Software Encoders +description: Software-based Encoders for Broadcasting Live Streaming Content +slug: /software-encoders +--- + +A software encoder can take raw video frames and convert it into a digital format that is compatible for distribution with the Dolby OptiView Live Streaming service. This type of integration can typically be done without additional hardware requirements and eases adoption of real-time streaming workflows. + +## Integration Guides + +Review these guides for how to setup your preferred tools for real-time streaming integrations. + +import { IconGrid, IconGridButton } from '@site/src/components/IconGrid'; + + + + [![FFMPEG](https://upload.wikimedia.org/wikipedia/commons/thumb/5/5f/FFmpeg_Logo_new.svg/2560px-FFmpeg_Logo_new.svg.png)](ffmpeg.md) + + [![OBS](https://upload.wikimedia.org/wikipedia/commons/d/d3/OBS_Studio_Logo.svg)](obs.md) + [![vMix](https://www.vmix.com/images/2017/logos/web/vmix-logo/vMix-Logo-Black.png)](vmix.md) + + +### FFmpeg + +**FFmpeg** is a free open-source software project with command-line tools for handling video, audio, and other multimedia. This can be helpful for quickly streaming a media file from disk. + +[How-to integrate with FFmpeg](ffmpeg.md) + +### Open Broadcaster Software (OBS) + +**OBS** is a free open-source application for broadcasting and recording streams from your desktop computer. + +[How-to integrate with OBS](obs.md) + +### vMix + +**vMix** is a Windows desktop applicationi that provides a vision mixer and encoder. + +[How-to integrate with vMix](vmix.md) diff --git a/theolive_versioned_docs/version-v1/contribution/software-encoders/obs.md b/theolive_versioned_docs/version-v1/contribution/software-encoders/obs.md new file mode 100644 index 000000000000..b219125e26f6 --- /dev/null +++ b/theolive_versioned_docs/version-v1/contribution/software-encoders/obs.md @@ -0,0 +1,69 @@ +--- +sidebar_position: 2 +sidebar_label: OBS +--- + +# Using OBS with THEOlive + +**Open Broadcaster Software (OBS)** is a free open-source software created for broadcasting and recording on your desktop. You can take advantage of this tool to stream high-quality video to your viewers using THEOlive. + +See the official [obsproject.com](https://obsproject.com) documentation for installation instructions and additional support about using OBS. + +:::tip Getting Started +If you haven't already, begin by following the [Getting Started](/theolive/getting-started.mdx) tutorial to create a THEOlive channel and start your first broadcast. +::: + +## Setting up a broadcast + +### 1. Add a source + +In the _Source_ section at the bottom of the OBS application, hit the + sign to add a new source. For example, selecting "Media Source" allows you to select an existing media file stored on your machine. Selecting "Display Capture" will record your screen. Selecting "Video capture device" will allow you to select a video input device like a webcam. + +![Selecting a source](../../assets/img/obssource.png) + +### 2. Configure stream settings + +Select _Settings_ in the _Controls_ section at the bottom right of the OBS application. Click on the _Stream_ tab on the left menu bar and configure the following: + +- Select "Custom..." as the _Service_ +- Copy your `rtmpPushUrl` from the channel details page in the THEOlive dashboard URL as _Server_ +- Copy your `streamKey` from the channel details page in the THEOlive dashboard as _Stream Key_ + +![Defining stream settings](../../assets/img/obsoutputsettings.png) + +Next, go to the _Output_ tab in the _Settings_ menu, and configure the following settings in order to achieve the lowest possible latency using THEOlive. + +- Output Mode: `Advanced` +- Bitrate: match the max bitrate of the profile used in your channel (e.g.: 4500Kbps for "sport"). [More details](../stream-configuration.mdx). +- Keyframe interval: `2s` +- CPU Usage Preset (higher = less CPU): `veryfast` +- Profile: `main` +- Tune: `zerolatency` + +![Defining output settings](../../assets/img/obsoutput.png) + +Lastly, go to the _Video_ tab and set the frame rate to the same value you have set in your THEOlive channel. See [Stream configuration](../stream-configuration.mdx) for more details. + +![Defining output settings](../../assets/img/obsfps.png) + +:::info 🚧 Upload bandwidth +Make sure that your encoder has a stable connection and enough upload bandwidth. This will ensure all data is correctly sent to the THEOlive channel. +::: + +### 3. Start streaming + +Hit apply on settings, close the window, and click on _Start Streaming_ in the _Controls_ panel in the bottom right corner of the OBS application. + +![Start streaming your video content](../../assets/img/obsstartstreaming.png) + +### 4. Start your THEOlive channel + +Your THEOlive channel must be started in order to receive video ingest from OBS. You can choose to start up your channel before or after you start streaming via OBS. + +Starting a channel can be done either [through the API](/theolive/api/channels/start-channel) or via [the console](https://console.theo.live/). + +![Start your channel](../../assets/img/consolechannelstart.png) + +## Feature compatibility and limitations + +- Ingest protocol must be RTMP push diff --git a/theolive_versioned_docs/version-v1/contribution/software-encoders/vmix.md b/theolive_versioned_docs/version-v1/contribution/software-encoders/vmix.md new file mode 100644 index 000000000000..8e739017e8b2 --- /dev/null +++ b/theolive_versioned_docs/version-v1/contribution/software-encoders/vmix.md @@ -0,0 +1,60 @@ +--- +sidebar_position: 4 +sidebar_label: vMix +--- + +# Using vMix with THEOlive + +This guide explains to you how to set up vMix correctly so it can be used to stream your content with THEOlive. + +## 1. Set up sources + +Make sure all your sources are set up and in order. As an example, you could add simple colour bars as a source by left-clicking the _up arrow_ next to _Add Input_, which you can find at the left bottom of the vMIX screen, and select _Colour Bars_. Similarly, you could add other input e.g. your webcam by selecting _Camera_ or a stream by selecting _Stream/SRT_. In order to see these options, you'll have to select _More_ in the _Add Input_ menu. + +![vMix setup example](../../assets/img/bcb0dde-vmix0.png) + +**Note:** The colour bars input are only an example. You can stream whatever input you like. + +:::info 📘 How to burn in a clock +If you want to burn in a clock you can follow the steps documented by vMix. You can create a _Production clock_ input and burn it into the colour bars input by configuring _Multiview_ +[Production clock documentation](https://www.vmix.com/help23/index.htm?ProductionClocks.html) +[Multiview documentation](https://www.vmix.com/help23/index.htm?InputSettingsMultiView.html) +::: + +## 2. Configure stream settings + +- Left-click the cogwheel next to _Stream_ at the bottom of the vMix screen. + +![vMix settings](../../assets/img/447bd06-vmix1.png) + +**Note:** Make sure you set up your settings first before clicking the _Stream_ button. + +- In the _Streaming Settings_ select _Custom RTMP Server_ as your destination and enter _your RTMP push URL and Streamkey_ as follows: + +![vMix streaming settings](../../assets/img/38e11d9-vmix-streaming-setting.PNG) + +**Note:** You can find your RTMP push URL and streamkey in the THEOlive management console. + +- Next, choose a set of stream values such as aspect ratio and bitrate from the _Quality_ list and click the cogwheel for advanced _Streaming Quality_ settings. + +![vMix quality settings](../../assets/img/73abc63-vmix3.png) + +**Note:** If you have the hardware available: it's always a good idea to enable the _Hardware Ecoder_ setting. + +- In the _Streaming Quality_ menu you can make some more advanced changes to your stream settings. Please use the settings that are highlighted in yellow in the following image to achieve optimal performance when streaming to THEOlive. You are free to change the _Video Bit Rates_ and _Encode Size_ settings depending on your use case. + +![stream quality settings](../../assets/img/fae9921-streaming-quality-settings.jpg) + +**Note:\*** You are free to experiment with your encoding settings but the values shown in this image reflect the encoding setting THEOlive uses on the server side. + +:::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. +::: + +## 3. Start streaming + +You can now save and exit out of all the _Streaming Settings_ menus and click the _Stream_ button to start streaming. + +## 4. Start your THEOlive channel + +This can be done either through the [API](/theolive/api/channels/start-channel) or via the [management console](https://console.theo.live/). diff --git a/theolive_versioned_docs/version-v1/contribution/software-encoders/wirecast.md b/theolive_versioned_docs/version-v1/contribution/software-encoders/wirecast.md new file mode 100644 index 000000000000..e4202e2f53f6 --- /dev/null +++ b/theolive_versioned_docs/version-v1/contribution/software-encoders/wirecast.md @@ -0,0 +1,71 @@ +--- +sidebar_position: 3 +sidebar_label: Wirecast +--- + +# Using Wirecast with THEOlive + +This guide explains to you how to set up Wirecast correctly so it can be used to stream your content with THEOlive. + +## 1. Configure Output Settings + +- Select "Output" from the toolbar +- Subsequently select "Output Settings..." + +![Selecting Output Settings](../../assets/img/17980ac-Wirecast_-_Output_Settings.jpg) + +- Select "RTMP Server" as the output destination and choose "OK". + +![Selecting RTMP server as Destination](../../assets/img/94e8600-Wirecast_-_Output_Destination.JPG) + +- Go to the THEOlive management console, and copy the RTMP Push URL and Stream key of your channel. +- Paste the RTMP Push URL into "Address". + +:::warning ❗️ Not all versions/editions of Wirecast support RTMPS +Definitely check whether your Wirecast version/edition supports RTMPS. Older versions typically do not support RTMPS, whereas for example the most recent version Professional version does support RTMPS. In case your version/edition does not accept RTMPS, then definitely change "RTMPS" to "RTMP" in your RTMP push URL. As an example rtmps://rtmp.europe-west.hesp.live/live will have to be changed to rtmp://rtmp.europe-west.hesp.live/live for RTMP-based streaming. +::: + +- Paste the Streamkey into "Stream:" + +![Setting the Address and Stream](../../assets/img/b212f75-Wirecast_-_RTMPurl__Streamkey.jpg) + +- Select your "Encoding" settings (max 1080p) +- Subsequently review your detailed encoding settings by clicking the settings button next to encoding, and selecting "view details" + +![Showing the detailed encoding settings](../../assets/img/42264c9-Wirecast_-_Detailed_Encoder_Settings.JPG) + +- Define the appropriate encoder latency, taking into account your computer performance. "1 - (Ultra Fast encoding)" will give the lowest latency as it requires the least CPU time. +- Also select the encoding "Profile". For example, "Main" will give lower latencies than "High" but on the other hand "High" will provide for better quality than "Main". +- Lastly, set "Frames per second" to the same value used in the THEOlive channel ingest config and set "Average bit rate" to match the max bitrate of the channel preset. See [Stream configuration](../stream-configuration.mdx) for more details. +- Click "OK" and move to step 2 to add your live stream. + +![Wirecast encoding quality](../../assets/img/48bc7d6-Wirecast_-_Encoding_Quality.png) + +:::info 🚧 Upload bandwidth + +Make sure that your encoder has a stable connection and enough upload bandwidth. This will ensure all data is correctly sent to the THEOlive channel. +::: + +## 2. Add a New Layer + +- Click the ‘+’ button on the top layer to add your live stream. + +![Adding a new layer](../../assets/img/fea4c5a-Wirecast_-_New_Layer.JPG) + +- Subsequently add your layer. In order to capture your webcam, for example, click on ‘Video Capture’ from the left. Next, select the video capture device you wish to add. + +![Selecting an option that should function as the layer](../../assets/img/7b3faa5-Wirecast_-_Select_Source.jpg) + +- You'll then need to activate the layer by clicking on the white arrow. + +![Activating the layer](../../assets/img/b4945ca-Wirecast_-_Activate_Layer.jpg) + +## 3. Start Streaming + +Click the "Stream" button. Wirecast will make a connection to the THEOlive RTMP server. + +![Start streaming](../../assets/img/2416285-Wirecast_-_Start_Streaming.jpg) + +## 4. Start your THEOlive channel + +This can be done either through the [API](/theolive/api/channels/start-channel) or via the [management console](https://console.theo.live/). diff --git a/theolive_versioned_docs/version-v1/contribution/stream-configuration.mdx b/theolive_versioned_docs/version-v1/contribution/stream-configuration.mdx new file mode 100644 index 000000000000..2f4b1e6d8605 --- /dev/null +++ b/theolive_versioned_docs/version-v1/contribution/stream-configuration.mdx @@ -0,0 +1,113 @@ +--- +sidebar_position: 1 +--- + +# Stream Configuration + +Settings related to the THEOlive stream output + +--- + +THEOlive offers pre-defined ABR profiles (or "presets") which allows you to adjust the stream settings according to your use case. Different pricing per minute transcoded and viewed applies to each profile. + +**Note:** this is a breaking change compared to the method where you had to pass a `ingestConfig` object in the past. This old approach is still available for the time being. More information can be found later on in this [document](#setting-the-stream-configuration-via-the-ingestconfig-object-deprecated). You can pass both a `streamConfig` as well as a `ingestConfig` object (the API won't throw an error), but `streamConfig` will take precedence. + +## Setting the stream configuration via the `streamConfig` object + +The goal is to pass a `streamConfig` object during the [creation](/theolive/api/channels/create-channel) of a channel, or when [updating](/theolive/api/channels/update-channel) it. This object consists of: + +- `bitrate`: the max bitrate value that will be used in Mbps. +- `resolution`: the max resolution that will be used. Possible values: `"1080p"`, `"720p"`, `"576p"`, `"480p"`. +- `fps`: the max fps value that will be used. Can be `25`, `29.97`, `30`, `50`, `59.94`, `60`. +- `abr`: a boolean to determine if ABR should be enabled or not. + +**Remarks:** + +- The `streamConfig`object is optional. When it's not passed, the following default values will be used: + - `bitrate: 4.5` + - `resolution: "1080p"` + - `fps: 30` +- When defining the `streamConfig` object, it's mandatory to pass _all_ properties (bitrate, resolution, fps). Otherwise, the API will return an error. + +In the table below you can find a complete overview of all possible values that can be passed and the ABR ladder in which it will result. Please refer to our [pricing page](https://www.theoplayer.com/pricing/theolive) for the latest pricings per profile. + +| Bitrate | Resolution | fps | ABR ladder | +| :------- | :--------- | :------------ | :----------------------------------------------------------------------- | +| 8 Mbps | 1080p | 50, 59.94, 60 | - 1080p @ 8 Mbps - 720p @ 4.5 Mbps - 576p @ 1.5 Mbps - 360p @ 0.9 Mbps | +| 8 Mbps | 1080p | 25, 29.97, 30 | - 1080p @ 8 Mbps - 720p @ 4.5 Mbps - 576p @ 1.5 Mbps - 360p @ 0.9 Mbps | +| 6 Mbps | 1080p | 50, 59.94, 60 | - 1080p @ 6 Mbps - 720p @ 3.5 Mbps - 576p @ 1.5 Mbps - 360p @ 0.9 Mbps | +| 6 Mbps | 1080p | 25, 29.97, 30 | - 1080p @ 6 Mbps - 720p @ 3.5 Mbps - 576p @ 1.5 Mbps - 360p @ 0.9 Mbps | +| 6 Mbps | 720p | 50, 59.94, 60 | - 720p @ 6 Mbps - 576p @ 4 Mbps - 360p @ 2 Mbps - 240p @ 0.9 Mbps | +| 6 Mbps | 720p | 25, 29.97, 30 | - 720p @ 6 Mbps - 576p @ 4 Mbps - 360p @ 2 Mbps - 240p @ 0.9 Mbps | +| 4.5 Mbps | 1080p | 50, 59.94, 60 | - 1080p @ 4.5 Mbps - 720p @ 3 Mbps - 576p @ 1.5 Mbps - 360p @ 0.9 Mbps | +| 4.5 Mbps | 1080p | 25, 29.97, 30 | - 1080p @ 4.5 Mbps - 720p @ 3 Mbps - 576p @ 1.5 Mbps - 360p @ 0.9 Mbps | +| 4.5 Mbps | 720p | 50, 59.94, 60 | - 720p @ 4.5 Mbps - 576p @ 2.5 Mbps - 360p @ 1.5 Mbps - 240p @ 0.9 Mbps | +| 4.5 Mbps | 720p | 25, 29.97, 30 | - 720p @ 4.5 Mbps - 576p @ 2.5 Mbps - 360p @ 1.5 Mbps - 240p @ 0.9 Mbps | +| 2.5 Mbps | 1080p | 25, 29.97, 30 | - 1080p @ 2.5 Mbps - 720p @ 2.2 Mbps - 576p @ 1.5 Mbps - 360p @ 0.9 Mbps | +| 2.5 Mbps | 720p | 25, 29.97, 30 | - 720p @ 2.5 Mbps - 576p @ 1.5 Mbps - 360p @ 0.9 Mbps | +| 2.5 Mbps | 576p | 25, 29.97, 30 | - 576p @ 2.5 Mbps - 360p @ 1.5 Mbps - 240p @ 0.9 Mbps | +| 1.5 Mbps | 720p | 25, 29.97, 30 | - 720p @ 1.5 Mbps - 576p @ 1 Mbps - 360p @ 0.9 Mbps | +| 1.5 Mbps | 576p | 25, 29.97, 30 | - 576p @ 1.5 Mbps - 360p @ 1 Mbps - 240p @ 0.9 Mbps | +| 1.5 Mbps | 360p | 25, 29.97, 30 | - 360p @ 1.5 Mbps - 240p @ 0.9 Mbps | +| 1 Mbps | 576p | 25, 29.97, 30 | - 576p @ 1 Mbps - 360p @ 0.9 Mbps - 240p @ 0.8 Mbps | +| 1 Mbps | 360p | 25, 29.97, 30 | - 360p @ 1 Mbps - 240p @ 0.8 Mbps | + +:::info 🚧 Encoder settings + +**Frame rate** +To obtain the best performance, set the same frame rate on both your encoder and in the channel configuration (the suggested values for this are 25, 29.97 or 30 fps). Frame rate differences between encoder and channel may lead to information loss and stalls. + +**Bandwidth** +Make sure your encoder has a stable connection with enough upload bandwidth to correctly serve all frames. Dropped frames or connection interruptions may lead to increased latency, stalls and playback failures. +::: + +## Setting the stream configuration via the `ingestConfig` object (deprecated) + +Before the `streamConfig` object was available in our API, you had to configure the settings using the `ingestConfig` object. This approach is still available to provide backwards compatibility for existing integrations, but it's not recommended to use anymore: it will be deprecated in the near future. + +We highly recommend to update your integration to make use of the new `streamConfig` object. + +For those still using the `ingestConfig` object: this object accepts a few properties. + +- `preset`: can be `"default"`, `"sport"`or `"presentation"`. Defaults to `"default"` when not passed. The connected ABR ladders can be found below +- `abr`: boolean. +- `aspectRatio`: used for setting the max resolution, but poorly named in the past. Depending on the resolution you choose, your ABR ladder will exist out of four steps (in case of `"1080p"`), three steps (in case of `"720p"`), two steps (in case of `"480p"`), or one step (in case of `"360p"`). +- `fps`: a number that can be 25, 29.97, 30, 50, 50.94, 60. + +### Default preset values + +The default configuration that will work for most use cases. + +| Quality | Bit rate | +| :--------- | :-------- | +| HD - 1080p | 4000 kbps | +| HQ - 720p | 2500 kbps | +| MQ - 480p | 1200 kbps | +| LQ - 360p | 900 kbps | + +### Sport preset values + +The ideal configuration for streams with fast-moving images and a lot of scene changes that have a high bit rate. An example can be a broadcasted football game. + +| Quality | Bit rate | +| :--------- | :-------- | +| HD - 1080p | 4500 kbps | +| HQ - 720p | 2700 kbps | +| MQ - 480p | 1400 kbps | +| LQ - 360p | 1000 kbps | + +### Presentation preset values + +The configuration that can be used when not a lot of scene changes are expected, think about a meeting with a few slides. + +| Quality | Bit rate | +| :--------- | :-------- | +| HD - 1080p | 2200 kbps | +| HQ - 720p | 900 kbps | +| MQ - 480p | 800 kbps | +| LQ - 360p | 450 kbps | + +:::info 📘 Ingest configuration + +When configuring your RTMP ingest, it is important to match the highest bitrate of your bitrate ladder. When using the recommended preset at 1080p for example, the RTMP ingest should be configured at 4000 kbps. +::: diff --git a/theolive_versioned_docs/version-v1/getting-started.mdx b/theolive_versioned_docs/version-v1/getting-started.mdx new file mode 100644 index 000000000000..cc4f7ada6be8 --- /dev/null +++ b/theolive_versioned_docs/version-v1/getting-started.mdx @@ -0,0 +1,117 @@ +--- +sidebar_position: 2 +sidebar_label: Getting started +--- + +# Backend + +THEOlive provides a REST API to manage channels, configure them and start / stop them. Each possible call can be found at our [API Reference](/theolive/api/channels/create-channel). + +However, to make things easier for non-developers, we built a management console on top of these API calls which makes it straightforward to perform the basic actions. To be able to create and use a THEOlive channel, you should register for an account and get a token to perform [authenticated requests](./platform/authorization.mdx) to our API. + +## 1. Create an account in the management console + +To start your journey, you'll have to create a THEOlive account in the [management console](https://console.theo.live/) . + +Once you've entered your username and password, you can already create your first channel and start streaming. + +![](assets/img/302e789-dashboard.png 'Homepage of the THEOlive management console') + +:::info 📘 API reference + +This guide describes how to get started with the THEOlive management console. Please consult the [API reference](/theolive/api/channels/create-channel) and [Authorization](./platform/authorization.mdx) if you would like to work with API calls. +::: + +## 2. Create your first channel + +Time to start streaming! In the management console, please click "create channel", which will return the following screen: here you can enter a name for your channel, choose the ingest location, and define your [Stream configuration](./contribution/stream-configuration.mdx). It is important to choose a location as close as possible to you to reduce latency. + +![](assets/img/b636bf5-create-channel.PNG 'Create a channel') + +When hitting 'Create', you will be navigated towards the Details page of your newly created channel. + +![](assets/img/467abb8-overview.PNG 'Management console: Details page with the possibility to start your channel and options to customize your player.') + +A channel can also be created through an API call to the `channels` endpoint, passing an ingest location and a name. It will return an `id` that you can use to start, stop, update or delete the channel later on. Also, a `streamKey` and `rtmpPushUrl` will be returned to stream your content to. More information about the Create channel endpoint and how to pass advanced properties can be found [here](/theolive/api/channels/create-channel). + +```curl +curl --location --request POST 'https://api.theo.live/channels' +--header 'Authorization: Basic dG9rZW46c2VjcmV0' \ +--header 'Content-Type: application/json' \ +--data-raw '{ + "ingestLocation": "europe-west", + "metadata": { + "name": "a-name" + } +}' +``` + +Note that for this API call you'll need a token that you can generate in the management console. More information can be found at the [Authorization](./platform/authorization.mdx) guide. + +## 3. Start streaming + +Using the RTMP push URL and the stream key you have received when creating a channel, you can start streaming content to that RTMP endpoint. + +:::info 🚧 RTMP pull + +If you would like to do pull-based streaming instead of push-based streaming, you can also use your own RTMP pull endpoint and specify this when starting the channel in the next step. +::: + +One option to start streaming content is making use of [OBS](https://obsproject.com/). It's an easy, free and quick way to get you started. More information on how to get started with OBS can be found in our guide [Using OBS with THEOlive](./contribution/software-encoders/obs.md). If you would be using [Wirecast](https://www.telestream.net/wirecast) for your live streaming, then more information on how to get started can be found in the guide [Using Wirecast with THEOlive](./contribution/software-encoders/wirecast.md). There are also guides for [vMix](./contribution/software-encoders/vmix.md) and [Videon Edgecaster](./contribution/hardware-encoders/videon.mdx). + +:::info ❗️ RTMPS vs RTMP + +The RTMP push URL generated by THEOlive shows as RTMPS. If you would like to do RTMP streaming then you will have to change "rtmps" to "rtmp". As an example, `rtmps://rtmp.europe-west.theo.live/live` will have to be changed to `rtmp://rtmp.europe-west.theo.live/live` for RTMP-based streaming. +::: + +## 4. Player embed script + +Now we have to make sure that our viewers have access to the stream! Including a THEOlive channel on your page is very simple: all you need is our embed script and the channel ID. The [Player](./playback/web/getting-started.mdx) guide gives more information on how to do this, including a code snippet example. + +### Obtaining a Player License for THEOlive + +THEOlive customers have access to THEOplayer Licenses with support for the following platforms: + +- `html5` +- `android` +- `androidtv` +- `firetv` +- `ios` +- `tizen` +- `tvos` +- `webos` + +These licenses can be found in the "Playout Configurations" section for each of your created Channels on your [THEOlive dashboard](https://console.theo.live/login) as pictured below: + +![](assets/img/theolive-license.png) + +Licenses will be automatically generated for each new channel you create. Aliases on the same channel will share the same license. + +## 5. Start the channel + +When you're all set, you can start your THEOlive channel. Starting your channel also means your [transcoding time](https://www.theoplayer.com/pricing/theolive) will start counting for billing purposes. + +You can easily start your channel on the channel details page, by clicking on the green "start" button. + +![](assets/img/cbe288c-start.PNG) + +In the background this will make a `POST` request to the `channels/start` endpoint. You can also start a channel via the Start channel API call, for which you can find more information [here](/theolive/api/channels/start-channel). As mentioned in the last section, you can optionally pass the `rtmpPullUrl` property in the body of the request for pull-based streaming. Don't forget to stop streaming when you are done! + +```curl +curl --location --request POST 'https://api.theo.live/channels/{channel-id}/start' \ +--header 'Authorization: Basic dG9rZW46c2VjcmV0' \ +--header 'Content-Type: application/json' \ +--data-raw '{ + "rtmpPullUrl": "your-optional-rtmp-pull-url" +}' +``` + +## 6. Stop the channel + +Have you finished your real-time streaming? Make sure to stop your channel by making a request to the `channels/stop` endpoint, either through a [Stop channel](/theolive/api/channels/stop-channel) API call or by pressing the red "stop" button in the management console. + +```curl +curl --location --request POST 'https://api.theo.live/channels/{channel-id}/stop' \ +--header 'Authorization: Basic dG9rZW46c2VjcmV0' \ +--header 'Content-Type: application/json' +``` diff --git a/theolive_versioned_docs/version-v1/index.mdx b/theolive_versioned_docs/version-v1/index.mdx new file mode 100644 index 000000000000..b75af0c319a9 --- /dev/null +++ b/theolive_versioned_docs/version-v1/index.mdx @@ -0,0 +1,17 @@ +--- +sidebar_label: Introduction +sidebar_position: 1 +--- + +# THEOlive + +import SidebarDocCardList from '@site/src/components/SidebarDocCardList'; + +THEOlive is a low latency streaming solution across various platforms and devices. It +delivers sub-second latency while maintaining exceptional playback quality and viewer experience. This all makes it perfect +for all kinds of use cases including but not limited to: live sports, sports betting and interactivity. + +On these pages, you'll learn how to get started with the THEOlive backend and player, how to use the various features, +and explore examples. + + diff --git a/theolive_versioned_docs/version-v1/platform/authorization.mdx b/theolive_versioned_docs/version-v1/platform/authorization.mdx new file mode 100644 index 000000000000..e9db8096adb3 --- /dev/null +++ b/theolive_versioned_docs/version-v1/platform/authorization.mdx @@ -0,0 +1,55 @@ +--- +sidebar_position: 1 +--- + +# Authorization + +To make secure calls to the THEOlive REST API, both authentication and authorization are required. THEOlive uses token–secret pairs to authorize API requests and ensure secure access. + +## 1. Getting a token-secret pair + +To generate a token–secret pair, you must first have an account on the [THEOlive management console](https://console.theo.live/). + +1. Navigate to the _Developers section_ and click on "Tokens". +2. Click the "Generate Token" button. +3. Enter a name for your token. +4. Click "Generate" to create the token–secret pair. + +![](../assets/img/c0aca77-1.-THEOlive-console-generate-token.PNG) + +This will open a pop-up displaying your token "key" and its corresponding secret. + +![](../assets/img/bb9b4a6-2.-THEOlive-console-generated-token-and-secret.PNG) + +:::warning[Please store the secret] + +Make sure to securely store the secret, as it will only be shown once. THEOlive stores a hashed version of the secret, meaning it cannot be recovered afterward. + +::: + +Once you close the pop-up window, the new token will be visible in your list of active tokens. + +![](../assets/img/5361242-3.-THEOlive-console-token-list.PNG) + +If you forget your secret or if it gets exposed, you can easily regenerate a new token–secret pair at any time. + +To revoke a token, click the arrow icon under the "Actions" column and the token will be moved to the list of revoked tokens after confirmation. + +## 2. Using the token-secret pair with Basic Authentication + +THEOlive uses Basic Authentication for API requests. To authenticate, include your token-secret pair (base64-encoded) in the 'Authorization' header, prepended with the word 'Basic'. + +Here’s an example of how to set up the header: + +1. Combine your token and secret in the format `token:secret`. + Example: `my-token:my-secret` + +2. Base64 encode the combined value. + Example: `bXktdG9rZW46bXktc2VjcmV0` + +3. Include the encoded string in the Authorization header, prefixed with the word Basic. + Example header: `Authorization: Basic bXktdG9rZW46bXktc2VjcmV0` + +4. The final Authorization header should look like this: `Authorization: Basic bXktdG9rZW46bXktc2VjcmV0` + +You’re now ready to make authenticated requests to the THEOlive API. diff --git a/theolive_versioned_docs/version-v1/platform/manage-team.mdx b/theolive_versioned_docs/version-v1/platform/manage-team.mdx new file mode 100644 index 000000000000..80bab42947b0 --- /dev/null +++ b/theolive_versioned_docs/version-v1/platform/manage-team.mdx @@ -0,0 +1,59 @@ +--- +sidebar_position: 0 +sidebar_label: Manage your team +--- + +# How to manage your team + +After signing up for the [THEOlive console](https://console.theo.live/login), you may want to collaborate with your colleagues using the same account and channels. This guide walks you through how to set up team access and collaboration. + +## 1. Manage your team + +### 1.1 - Access the team + +Click on the “My account” button, on the top right-hand corner of the screen and select _My Team_. + +![](../assets/img/22fb225-my-team.PNG 'My team in top right-hand corner menu') + +This section displays all members of your team along with their current status. Each member is assigned a role as either an admin or user. + +![](../assets/img/e35aec9-2.Team.PNG 'Team') + +:::warning 🚧 Only admins can access the _My Team_ section +The _My Team_ section is only visible to admins. If you don’t see the _My team_ button, it means you currently don’t have admin rights. You can find more information about roles in the section below. +::: + +### 1.2 - Add member + +To invite a colleague, click on the _Add member_ button. Enter their email address, select their role, and click _Add_ to confirm. + +![](../assets/img/fe6b54f-3._New_user.jpg 'New user') + +An invitation has been sent to the specified email address, including a link and instructions to access the THEOlive console. + +If needed, you can resend the invitation from the _My Team_ page by clicking the envelope icon next to the user's name (see screenshot below). + +Once your colleagues accept the invitation, they’ll have access to the same console account. The _My Team_ page will then display them as part of your team. + +![](../assets/img/3030fa6-4.Whole_team.PNG 'Whole team') + +## 2. Determining the role of your new team members + +There are two roles defined in the THEOlive console: **admin** and **user**. While both roles have access to most of the same information and actions, admins have a few additional permissions. + +Admins can: + +- Access team management and billing pages +- Grant or revoke admin access for other team members +- Remove members from the team +- Revoke tokens + +Users can perform most day-to-day tasks but do not have access to team management, billing, or token revocation. + +## 3. Complete your profile + +When a user is invited to a THEOlive team, they gain access to the _My Profile_ page. Here, they can update their personal details, including first name, last name, phone number, and password. + +Access to this page is restricted to the individual user. Neither other team members nor admins can view or edit someone else’s personal information. + +![](../assets/img/3aad379-5.Personal_info.PNG 'Personal info') diff --git a/theolive_versioned_docs/version-v1/platform/multi-channel.md b/theolive_versioned_docs/version-v1/platform/multi-channel.md new file mode 100644 index 000000000000..d41730039b80 --- /dev/null +++ b/theolive_versioned_docs/version-v1/platform/multi-channel.md @@ -0,0 +1,45 @@ +--- +sidebar_position: 2 +sidebar_label: Alias +--- + +# Multi-channel: aliases for channels + +This guide outlines THEOlive’s multi-channel approach: ingest your stream once and create multiple channel aliases, each with its own unique playout configuration. In addition to customized settings per alias, THEOlive also allows you to apply individual security features—such as geoblocking and token-based authentication on a per-alias basis. + +You can configure this via the [THEOlive management console](https://console.theo.live), as well via the [THEOlive API](/theolive/api/channels/create-channel-alias). + +## Multi-channel: player aliases + +Do you want to deliver your live stream to multiple customers at the same time—each with a personalized player experience, region-specific access restrictions, and separate usage analytics? THEOlive’s player alias capability makes this easy. + +From the "_Channel Details_" page, you can create channel aliases under the "_Playout Configurations section_". Each alias can be customized with its own playout settings, including player colors, poster image, announcement message, logo, and more. + +![Create a new channel alias under the "Playout configurations" tab](../assets/img//9ce6eb8-Create_channel_alias.jpg) + +The key advantage of this approach is that you only need to configure your ingest once, and then distribute your content across multiple web pages—each using a different channel alias with its own unique Channel ID. + +Including an alias is straightforward: Copy the alias’s Channel ID and paste it as the value of the `data-theo-live-id` attribute. For detailed instructions, go to the "_Include channel on your page_" tab, where you’ll find a step-by-step guide on embedding a specific playout configuration (alias) into your web page. + +![Find the unique channel ID of your alias in the "Include channel on your page" tab](../assets/img/6a57e61-channel-alias-include.png) + +### Managing your alias + +At any time, you can [update](/theolive/api/channels/update-channel-alias), [enable](/theolive/api/channels/enable-channel-alias), [disable](/theolive/api/channels/disable-channel-alias) or [delete](/theolive/api/channels/delete-channel-alias) a channel alias. The default alias can't be deleted, you'll have to delete your whole channel in case you want to do so. + +![Icon buttons to disable, enable or delete an alias](../assets/img/8751d4a-alias-settings.PNG) + +### Analytics per channel alias + +You can visualize data for each channel alias individually. In the Console, the Analytics section of the Channel Details page provides insights such as concurrent viewers, latency, viewer locations, browser and operating system breakdowns, and total viewing minutes. Click on any of the links in the Analytics section to view detailed metrics for a specific alias. + +THEOlive also offers an API endpoint where you can query the minutes viewed on an hourly basis per channel alias. You can read more about it [here](/theolive/api/channels/get-channel-alias-analytics). + +![Link to viewing insights and channel usage page where analytics are stored per channel alias](../assets/img/3c77b57-channel-alias-analytics.png) + +# Multi-channel: Use-cases for channel aliases + +Creating channel aliases can serve useful in a couple of different ways. Here are a couple of examples where creating a channel alias can simplify your workflow + +- Creating a stream that requires multiple stream [redundancy](/theolive/platform/redundancy/) or fallback solutions +- Creating a stream that requires different [geo-blocking](/theolive/platform/security/geo-blocking) rules for different countries diff --git a/theolive_versioned_docs/version-v1/platform/real-time-update-with-webhooks.mdx b/theolive_versioned_docs/version-v1/platform/real-time-update-with-webhooks.mdx new file mode 100644 index 000000000000..847139b146f9 --- /dev/null +++ b/theolive_versioned_docs/version-v1/platform/real-time-update-with-webhooks.mdx @@ -0,0 +1,213 @@ +--- +sidebar_position: 9 +sidebar_label: Webhooks +--- + +# Real-Time Updates with webhooks + +--- + +This guide describes how you can leverage THEOlive webhooks to receive real-time updates about your THEOlive components. You don't need to query for updates yourself anymore: we send you information when certain events happen. This guide will first explain what webhooks are, how you can create and manage them via the THEOlive console and/or API, and finally describe how you can secure your webhooks. + +## 1. How it works + +When creating a webhook, you pass an endpoint URL that you control to THEOlive. This endpoint will be used by THEOlive to send real-time updates when certain events happen. It's important that this an HTTPS endpoint which is reachable by THEOlive. + +You can choose on which events THEOlive has to send a message to your endpoint. For example: you can choose to get notified when a channel reaches the "playing" mode, but also when it got deleted, stopped, created, etc. A full list of available events can be found [at the bottom of this page](#5-list-of-possible-events). + +The main advantage of webhooks is that THEOlive informs you in real-time when an event happens, and you don't have to pull our API continuously to check if there are any updates on an object. + +![](../assets/img/d2e680e-webhooks.png 'webhooks') + +## 2. Create and manage your webhooks + +You can create a webhook through the THEOlive API, or via the management console. In this document we will mainly describe the console approach, the full API reference for the actions and methods can be found [here](/theolive/api/webhooks/create-webhook). + +To create a webhook, click on "Webhooks" on the sidebar, followed by "Create". A webhook expects a name, a valid HTTPS endpoint, an optional description and a list of events it should listen and act on. A full list of events can be found at the bottom of this page. You can also select to listen to all possible events. When using the API, you can pass `events: ["*"]` when a webhook should listen to all events. + +![](../assets/img/a1acade-create-webhook.PNG 'Creating a webhook through the console') + +When such an event happens, THEOlive will try to send a request to your endpoint. **It's important that you inform us as soon as possible that you received the request with a status 200 code**: requests that take longer than 3 seconds will be terminated by THEOlive and marked as failed. When a webhook has too many failed attempts, THEOlive will disable the webhook automatically. Below, we show a small code example of an Express app where we inform THEOlive we have received the request, before we do all other actions: + +```javascript +const express = require('express'); +const port = 3000; + +var app = express(); + +app.use(express.json()); + +app.post('/webhooks', (req, res) => { + res.send('ok'); // let us know ASAP you received our request + + // your app-specific implementation like updating your database etc. +}); + +app.listen(port, () => { + console.log(`Example app listening on port ${port}`); +}); +``` + +:::warning 🚧 Newly created webhooks will be disabled by default + +When you create a webhook, it won't be active yet. THEOlive does this so you can test things out before we actually start firing events to your endpoint. When you think you are fully ready to receive webhook messages from THEOlive, you can enable the webhook through the console, or via the [/webhooks/$\{webhook-id\}/enable](/theolive/api/webhooks/enable-webhook) endpoint. +::: + +When a webhook is created, you can update or delete it through the API or management console. At the details page you can also see the history of all message that have been sent to your endpoint, and if they've failed or not. + +![](../assets/img/57e33f4-manage-webhook.PNG 'Webhook details page: option to manage your webhook, and a historical overview of all webhook messages that THEOlive sent to your endpoint') + +## 3. How to act on event + +THEOlive sends a JSON body along with the request which contains all necessary information. This JSON body has the following format: + +```json Request body example +{ + "created": 1661435007, + "type": "channel.playing", + "object": { + "type": "channel", + "id": "" + }, + "livemode": true +} +``` + +- `created` is a Unix timestamp when the event happened +- `type` is the [type of event](#5-list-of-possible-events) that got fired +- `object` contains two properties: `type` is the type of the object, `id` the ID of it. +- `livemode`: a boolean to indicate if the request was a test or not + +In your implementation, you can use this data to act on it accordingly. In the example below, we will act differently on receiving a `channel.playing` and `channel.deleted` event: + +```javascript Act on events +const express = require('express'); +const port = 3000; + +var app = express(); + +app.use(express.json()); + +app.post('/webhooks', (req, res) => { + res.send('ok'); // let us now ASAP you received our request + + const data = req.body; + + switch (data.type) { + case 'channel.playing': + setChannelActiveInMyDatabase(data.object.id); // Fictional code somewhere in your implementation + case 'channel.deleted': + console.log('Something got deleted'); + default: + console.log('No code for this type implemented yet'); + } +}); + +app.listen(port, () => { + console.log(`Example app listening on port ${port}`); +}); +``` + +## 4. Add security to your webhooks + +THEOlive makes use of webhook signatures to verify that the webhook request was coming from us, and not from a server that was acting like THEOlive. On every request THEOlive will send a `THEOlive-Signature` header that you can use to check if it was really THEOlive that sent the message. + +### How does the verification work? + +Upon the creation of a webhook, you'll receive a `secret` that looks like `theosec_some-random-characters`. This is a key you can use in a later stage to do the necessary security checks. + +When receiving a webhook request from THEOlive, the `THEOlive-Signature` will always get sent with it and looks similar to the following: +`t=1659622850,h=6bbe0553922a31ea48cb3af9903616c3a8b65351434653251949480f2a91c037` + +This is a string that you have to de-structure yourself to get the value of `t` and `h`: + +- `t` is the Unix timestamp when the request got made. THEOlive adds this to prevent replay attacks. +- `h` is a hexadecimal HMAC SHA-256 hash, which is a combination of the timestamp `t` and the JSON body of the request, signed with your `secret`. + +As a user, you have to try to recreate the hash `h` yourself: you take `t`, add a stringified version of your JSON body after it, and hash it with the `secret` you received upon webhook creation. If the result equals to `h`, you can be sure the request was made by THEOlive. If not, someone tried to act like THEOlive. + +### Full code sample + +```javascript Check THEOlive-Signature for security +const express = require('express'); +const crypto = require('crypto'); +const port = 3400; + +var app = express(); + +app.use(express.json()); + +app.post('/webhooks', (req, res) => { + res.send('ok'); // let us now ASAP you received our request + + const secret = 'theosec_myverylittlesecret'; // secret received on creation, can be retrieved anytime at the THEOlive console + const data = req.body; // body of the request + + // 1. Grab THEOlive-Signature from header + const theoHeader = req.header('THEOlive-Signature'); // t=1659622850,h=6bbe0553922a31ea48cb3af9903616c3a8b65351434653251949480f2a91c037 + + // 2. Split string: you'll receive a timestamp (t) and hash (h) + const timestampPart = theoHeader.split(',')[0]; // t=1659622850 + const hashPart = theoHeader.split(',')[1]; // h=6bbe0553922a31ea48cb3af9903616c3a8b65351434653251949480f2a91c037 + + // 3. Get the values for both the timestamp and hash + const timestampValue = timestampPart.split('=')[1]; // 1659622850 + const hashValue = hashPart.split('=')[1]; // 6bbe0553922a31ea48cb3af9903616c3a8b65351434653251949480f2a91c037 + + // 4. Prepare the hash string: stringify the request body + const dataAsString = JSON.stringify(data); // {"created":1659622849,"data":{"id":"9uiwh5owynp3ympsxqtjxa3zd","type":"channel"},"type":"channel.created","livemode":false} + const stringToBeHashed = `${timestampValue}.${dataAsString}`; // 1659622850.{"created":1659622849,"data":{"id":"9uiwh5owynp3ympsxqtjxa3zd","type":"channel"},"type":"channel.created","livemode":false} + + // 5. Make a HMAC SHA-256 hash, using your secret as a key + const hashToCheck = crypto.createHmac('sha256', secret).update(stringToBeHashed).digest('hex'); // 6bbe0553922a31ea48cb3af9903616c3a8b65351434653251949480f2a91c037 + + // 6. Check if both hashes are the same + if (hashToCheck === hashValue) { + // all good, continue with code + } else { + // data not coming from THEOlive, throw an error + } +}); + +app.listen(port, () => { + console.log(`Example app listening on port ${port}`); +}); +``` + +## 5. List of possible events + +| Type | Description | +| :--------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `channel.creating` | Occurs when someone initiated a creation of a channel. | +| `channel.created` | Occurs when the creation of a channel is completed. | +| `channel.stopping` | Occurs when someone decides to stop a channel. | +| `channel.stopped` | Occurs when all procedures to stop a channel are completed. | +| `channel.deleting` | Occurs when someone decides to delete a channel. | +| `channel.deleted` | Occurs when the process to delete a channel is completed. | +| `channel.error` | Occurs when a channel goes into error state. | +| `channel.deploying` | Occurs when someone starts a channel and all infrastructure starts deploying. | +| `channel.starting` | Occurs when all infrastructure is deployed and channel is starting up. | +| `channel.waiting` | Occurs when channel is ready, but isn't receiving ingest yet. | +| `channel.ingesting` | Occurs when channel is receiving ingest. | +| `channel.playing` | Occurs when manifest is ready and channel can playout content. | +| `channel.scheduled` | Occurs when a channel has a scheduled start time due to a scheduler. The channel itself is ready, but the stream will be available for the viewers at scheduler start time. | +| `channel.log.warn` | Occurs when a warning message for a channel gets received. | +| `channel.log.error` | Occurs when an error message for a channel gets received. | +| `channel.log.info` | Occurs when an info message for a channel gets received. | +| `channel.updated` | Occurs when a channel got updated. | +| `alias.created` | Occurs when an new alias got created. | +| `alias.disabled` | Occurs when an alias got disabled. | +| `alias.enabled` | Occurs when an alias got enabled. | +| `alias.deleted` | Occurs when the process to delete an alias is finished. | +| `alias.updated` | Occurs when an alias got updated. | +| `webhook.created` | Occurs when a webhook got created. | +| `webhook.enabled` | Occurs when a webhook got enabled. | +| `webhook.disabled` | Occurs when a webhook got disabled. | +| `webhook.updated` | Occurs when a webhook got updated. | +| `webhook.deleted` | Occurs when a webhook got deleted. | +| `scheduler.created` | Occurs when a scheduler got created. | +| `scheduler.updated` | Occurs when a scheduler got updated. | +| `scheduler.deleted` | Occurs when a scheduler got deleted. | +| `scheduler.starting` | Occurs when a scheduler moves to starting mode: all connected channels will start up, stream will not be shown to your users yet. | +| `scheduler.active` | Occurs when a scheduler moves to active mode: the stream is now shown to your users. | +| `scheduler.terminated` | Occurs when a schedulers gets terminated. | diff --git a/theolive_versioned_docs/version-v1/platform/redundancy.md b/theolive_versioned_docs/version-v1/platform/redundancy.md new file mode 100644 index 000000000000..f34a950d424f --- /dev/null +++ b/theolive_versioned_docs/version-v1/platform/redundancy.md @@ -0,0 +1,59 @@ +--- +sidebar_position: 3 +--- + +# Redundancy + +With THEOlive we want to make sure your viewers can continue watching your stream, even if there is an ingest failure or if there are connectivity problems in a certain location. It is hence possible to set up a fallback stream. This means that if one stream is unavailable for a short amount of time, the player checks if the fallback stream is available and switches the player source automatically to this stream. In this case, the viewers only see a small interruption and can continue watching without having to act. + +**Note:** Setting a fallback is possible on channel and on channel alias level. Example + +- Channel A has aliases A1 and A2 +- Channel B has aliases B1 and B2 + +This means + +- Channel A can fallback to Channel B, or to one of the aliases of B (B1, B2) +- An alias of channel A (for example alias A1), can fall back to channel B, or one of its aliases (B1, B2) +- Channel B can fall back to channel A, or aliases A1, A2 +- An alias of channel B can fall back to channel A, or aliases of it (A1, A2) +- It's not possible for channel A to fall back to an alias of itself (A1, A2), or for an alias to fall back to its parent channel (A1 to A). The same applies for channel B and its aliases. + +In what follows, we describe the approach to set a fallback for one channel. + +## 1. Create two channels and start them. + +You'll need to create two THEOlive channels via the [API](/theolive/api/channels/create-channel) or [management console](https://console.theo.live/). Let's say for example that we have the following channels with fictive IDs: + +- Channel `` which is located in the `us-west` region +- Channel `` which is located in the `us-east` region + +Don't forget to start both channels. If the fallback stream isn't started, it will be impossible to switch to it when something goes wrong with the primary one! + +## 2. Set the `fallback` using the THEOlive API + +Assume the channel with ID `` should have a fallback that links to the `` channel. To make this work, we need to send a request to the `PATCH https://api.theo.live/channels/` endpoint to update the settings of ``. Passing the following JSON body with the request will set the `` channel as the fallback channel. + +```json +{ + "fallback": { + "src": "", + "enabled": true + } +} +``` + +This will work as follows: + +1. Before starting anything, the player will check if the primary channel has been started (`` in our case). +2. If the channel is playing, the player will start playing. If the channel has not been started yet, a message will be shown that the live stream isn't started yet. +3. When the primary stream becomes unavailable after a while, the player will check if a fallback is defined and switch to it if possible. +4. If this fallback becomes unavailable after a while, the player will try to switch back to the primary stream. +5. This process will continue to work this way. If both streams are unavailable, the pre-live settings will be shown (an announcement message and optionally a poster image too). +6. When the primary channel is stopped, all players will stop playing (even if the fallback channel is still streaming). + +For more information, please visit our [API Reference](/theolive/api/channels/update-channel). + +Note that the fallback can also easily be set in our management console on the Channel Details page. Scroll down to the **Playout Configurations** section and select the _Fallback_ tab. + +![Setting a fallback through the management console](../assets/img/8d77256-Screenshot_2023-06-28_131652.png) diff --git a/theolive_versioned_docs/version-v1/platform/scheduler.mdx b/theolive_versioned_docs/version-v1/platform/scheduler.mdx new file mode 100644 index 000000000000..60342062fdc8 --- /dev/null +++ b/theolive_versioned_docs/version-v1/platform/scheduler.mdx @@ -0,0 +1,80 @@ +--- +sidebar_position: 10 +sidebar_label: Scheduler +--- + +# Schedule THEOlive channel start & stop + +## Define when a channel should be ready and when it should be stopped + +THEOlive allows you to automatically schedule the start and stop of a channel, offering several key advantages: + +- System readiness: All necessary components of the THEOlive stack will be up and running at the scheduled time. +- Lower development effort: No need to build and maintain your own scheduling system, saving time and reducing costs. +- Avoid wasted resources: Prevent unnecessary transcoding minutes by ensuring channels stop automatically when no longer needed. + +## How it works + +**What is a Scheduler in THEOlive?** + +A scheduler is a configuration that includes a **start time**, an optional **end time**, and a **list of channels** to start and stop automatically at those times. + +- **End time** is optional: If you don’t specify one, you’ll need to manually terminate the scheduler. This can be useful if you're unsure when your event will end. + +**How Scheduled Start Works** + +15 minutes before the scheduled start time, the associated channels enter a `scheduled` state. During this period: + +- The entire THEOlive stack begins spinning up. +- The THEOlive player will show no content—just as if the channel were in a stopped state. + +Start times under 15 minutes: You can create a scheduler with a start time less than 15 minutes in the future or even immediately by omitting the `start` property in the API. While the channels will still attempt to go live, THEOlive cannot guarantee the stream will be ready exactly on time due to infrastructure startup time. + +At the scheduled start time, the channel switches to `playing` mode and begins streaming to viewers. + +At the end time (or if the scheduler is manually terminated) the channel will stop. + +**Post-stream Usage Report** + +Approximately 15 minutes after the scheduler ends, THEOlive generates a usage report. This report includes: + +- Seconds viewed per channel +- Channel alias +- Viewer data by country +- Viewer platform data (OS, browser, versions, etc.) +- And more detailed insights + +## Creating and managing a scheduler through the API + +Setting up a schedule via the THEOlive API is quick and straightforward. For full implementation details, refer to the [Create scheduler](/theolive/api/schedulers/create-scheduler) API documentation. + +- **Updating a scheduler**: You can modify a scheduler at any time before or during its active period. +- **Manual termination**: If your events ends early or you didn't set an end time, you can manually stop the scheduler using the [Terminate scheduler](/theolive/api/schedulers/terminate-scheduler) endpoint. +- **Deleting a scheduler**: If the scheduler hasn’t started yet, it can be removed using the [Delete scheduler](/theolive/api/schedulers/delete-scheduler) endpoint. +- **Accessing usage reports**: About 15 minutes after a scheduler has ended or been terminated, a detailed report becomes available via the [Get scheduler report](/theolive/api/schedulers/get-scheduler-report) endpoint. + +## Scheduler management in the console + +You can view the status of all schedulers at any time, including those that are active, pending, or terminated. + +Active schedulers cannot be deleted. + +![](../assets/img/cd5c594-scheduler-overview.png 'Scheduler overview') + +When creating a new or managing an existing scheduler, you can pass a name, start and (optional) end date, and select the channels that are part of this scheduler and should start and stop at the given timestamps. + +As a user, you can also pass an optional _Client ID_, which is an ID you can use for your reference. You can also pass a metadata object, which consists of key-value pairs. + +When creating a new scheduler or managing an existing one, you can specify the following: + +- **Name**: A custom name for the scheduler. +- **Start and End Dates**: Define the start time, and optionally, the end time. +- **Channels**: Select the channels that will be part of this scheduler, specifying which should start and stop at the defined times. +- **Repeat schedule**: Allow the specified schedule to be repeated based on settings. + +In addition, you can include the following optional fields as a user: + +- **Client ID**: A unique identifier for your reference. +- **Metadata Object**: A set of key-value pairs that you can use to store additional custom information. + +![](../assets/img/8ce9112-create-scheduler.PNG 'Creating a new scheduler') diff --git a/theolive_versioned_docs/version-v1/platform/security/_category_.json b/theolive_versioned_docs/version-v1/platform/security/_category_.json new file mode 100644 index 000000000000..c9fdf17d52a0 --- /dev/null +++ b/theolive_versioned_docs/version-v1/platform/security/_category_.json @@ -0,0 +1,6 @@ +{ + "label": "Security", + "customProps": { + "icon": "🔐" + } +} diff --git a/theolive_versioned_docs/version-v1/platform/security/geo-blocking.md b/theolive_versioned_docs/version-v1/platform/security/geo-blocking.md new file mode 100644 index 000000000000..dee5cc9cdc7c --- /dev/null +++ b/theolive_versioned_docs/version-v1/platform/security/geo-blocking.md @@ -0,0 +1,103 @@ +# Geo-blocking + +Geo-blocking refers to the action of restricting ("blacklisting") or allowing ("whitelisting") access to certain content based on the geographical location of the user. Filtering can be allowed or denied by countries as well as [IP addresses](/theolive/platform/security/ip-blocking). Geo-blocking enables content providers to adhere to specific licensing agreements and distribution rights, protect copyrighted material, or service another layer of privacy when working on private content. + +Geo-blocking can be configured via the API or the console. + +## Geo-blocking via the API + +### Main channel + +You can enable geo-blocking on a channel by [updating](/theolive/api/channels/update-channel) the `geoBlocking` object within `publicationConfig`. The `mode` of geo-blocking can also be configured: + +- `whitelist`: Used by default when no `mode` is passed. This will make the content only available in the countries that have been specified in the `countries` property. Countries not listed in the `countries` property will not receive the stream. +- `blacklist`: Blocks the content in the countries that have been specified in the `countries` property. All other countries not specified in the `countries` property will be able to view the content. + +:::tip +Countries should be passed in [ISO 3166-1 alpha-2 codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) +::: + +For example: If you want to restrict the viewers of your content to only Belgium and Germany, you can pass the following request: + +```json Enable geo-blocking on a channel +{ + "publicationConfig": { + "geoBlocking": { + "enabled": true, + "countries": ["BE", "DE"], + "mode": "whitelist" + } + } +} +``` + +If you would like to disable geo-blocking on this channel, you can pass the same request as above, but with: + +- `"enabled": false` +- `countries` can be omitted as it will be ignored + +```json Enable geo-blocking on a channel +{ + "publicationConfig": { + "geoBlocking": { + "enabled": false, + "mode": "whitelist" + } + } +} +``` + +If you would like to make your content available anywhere **except** Belgium, you can pass the following request: + +```json Use blacklist geo-block +{ + "publicationConfig": { + "geoBlocking": { + "enabled": true, + "countries": ["BE"], + "mode": "blacklist" + } + } +} +``` + +### Channel alias + +Geo-blocking can also be done on a [channel alias](/theolive/platform/multi-channel) using the specified channel alias [endpoint](/theolive/api/channels/update-channel-alias) or via the console. + +## Geo-blocking on main channel and alias + +Combining geo-blocking rules on both the main channel and aliases can allow you to create custom rules on where your content can be viewed in the world. + +For example, a stream you have created must adhere to the following rules: + +- Customer 1 can only show the stream to Belgian viewers +- Customer 2 can only show the stream to UK and USA viewers +- Customer 3 can only show the stream to French viewers + +In this scenario, you can create 3 aliases of your main channel, one for each customer. This allows you to set custom geo-blocking rules for each customer as well as [track customer specific analytics](../multi-channel.md). + +The main channel's `channel-id` won't be used, we so can geo-block it completely. This means someone using this channel ID will not be able to see it anywhere in the world. + +We will configure the 3 aliases with the following configurations: + +- Customer 1 will use channel ID `alias-1` where we `enable` geo-blocking and restrict the access to `BE` using `whitelist` in the the `mode` property. +- Customer 2 will use channel ID `alias-2` where we `enable` geo-blocking and restrict the access to `UK` and `US` using `whitelist` in the the `mode` property. +- Customer 3 will use channel ID `alias-3` where we `enable` geo-blocking and restrict the access to `FR` using `whitelist` in the the `mode` property. + +![Example of geo-blocking setup with channel and aliases](../../assets/img/48b69bf-Geoblocking.png) + +## Geo-blocking via the console + +Updating geo-blocking settings can also be done via the console. Navigate to your channel's details page and scroll down to the playout configurations panel. Select the your default channel or alias and click on the security tabs. If you don't have an alias, click the _Create Alias_ button on the top right of the panel. + +Clicking the toggle button can enable and disable geo-blocking on the specified channel. When enabled, a mode can be selected and countries can be added to the list. + +Don't forget to hit "Save" to apply your changes. + +![Geo-blocking settings in the console](../../assets/img/geoblockconsole.png) + +## Feature compatibility and limitations + +- Geo-blocking can be enabled or disabled during the middle of a stream without needing to restart the channel or restart ingests +- IP-blocking for a specified CIDR will not work if geo-blocking is enabled for the country or region where the CIDR originates from diff --git a/theolive_versioned_docs/version-v1/platform/security/ip-blocking.md b/theolive_versioned_docs/version-v1/platform/security/ip-blocking.md new file mode 100644 index 000000000000..66dac892f4a3 --- /dev/null +++ b/theolive_versioned_docs/version-v1/platform/security/ip-blocking.md @@ -0,0 +1,48 @@ +# IP-blocking + +IP-blocking (or IP-banning) refers to a security measure that restricts access to content for specific IP addresses. Filtering can be allowed or denied by IP addresses or by [countries](/theolive/platform/security/geo-blocking) as well. Only IPv4 and IPv6 CIDRs (Classless Inter-Domain Routing) are allowed. + +IP-blocking can be configured via the API or the console. + +## IP-blocking via the API + +### Main channel + +You can enable IP-blocking on a channel by [updating](/theolive/api/channels/update-channel) the `ipBlocking` object within `publicationConfig`. The `mode` of geo-blocking can also be configured: + +- `whitelist`: Used by default when no `mode` is passed. This will make the content only available for the CIDRs that have been specified in the `cidrs` property. CIDRs not listed in the `cidrs` property will not receive the stream. +- `blacklist`: Blocks the content for the CIDRs that have been specified in the `cidrs` property. All CIDRs not specified in the `cidrs` property will be able to view the content. + +For example: If you want to restrict certain CIDRs from viewing your content, you can pass the following request: + +```json Enable ip-blocking on a channel +{ + "publicationConfig": { + "ipBlocking": { + "enabled": true, + "mode": "whitelist", + "cidrs": ["170.123.145.2", "170.123.145.3"] + } + } +} +``` + +### Channel Alias + +IP-blocking can also be done on a [channel alias](/theolive/platform/multi-channel) using the specified channel alias [endpoint](/theolive/api/channels/update-channel-alias) or via the console. + +## IP-blocking via the console + +Updating IP-blocking settings can also be done via the console. Navigate to your channel's details page and scroll down to the playout configurations panel. Select the your default channel or alias and click on the security tabs. If you don't have an alias, click the _Create Alias_ button on the top right of the panel. + +Clicking the toggle button can enable and disable IP-blocking on the specified channel. When enabled, a mode can be selected and CIDRs can be added to the list. + +Don't forget to hit "Save" to apply your changes. + +![Geo-blocking settings in the console](../../assets/img/ipblockconsole.png) + +## Feature compatibility and limitations + +- IP-blocking can be enabled or disabled during the middle of a stream without needing to restart the channel or restart ingests +- IP-blocking for a specified CIDR will not work if geo-blocking is enabled for the country or region where the CIDR originates from +- IP-blocking only allows IPv4 and IPv6 CIDRs diff --git a/theolive_versioned_docs/version-v1/platform/security/token-based-security.mdx b/theolive_versioned_docs/version-v1/platform/security/token-based-security.mdx new file mode 100644 index 000000000000..f5a4716a2dd2 --- /dev/null +++ b/theolive_versioned_docs/version-v1/platform/security/token-based-security.mdx @@ -0,0 +1,58 @@ +# Token based security + +THEOlive offers the option to enable JWT token security for your distribution (formerly referred to as an alias). This can be interesting if you only want valid users to access your stream. + +In this document, we will + +- explain how it works +- how to enable/disable it via the console and API +- how to configure your THEOplayer to pass the mandatory headers + +## How it works + +When enabling token security on a distribution, we expect you to share the shared (private) key in case of HS256/HS512 or the public key in case of RS256/RS512 encryption. This will be used on CDN level to determine if a request (with a Bearer token passed in the `Authorization` header) is valid or not. It's up to you to configure this header correctly through our player. Later in this document we will explain how. + +In the bearer token that gets sent to us, we _require_ the following properties to be provided in the `payload`: + +- `exp`: date in epoch format until which the JWT token is valid +- `nbf`: optional date in epoch format. Stands for "not before" and acts as a "start date" of the JWT to be valid. + +When not passing a bearer token for a secured distribution, the request will be rejected. If the distribution is not secured, you may still pass a token but it is not required. + +![token based security](../../assets/img/dcdfc37-token_security.png) + +Putting it all together, here is an example of a token `payload`: + +```json +{ + "nbf": 1750786626 // optional, viewers attempting to connect before this time will not be permitted + "exp": 1750796626 // required, must be a valid time in the future to allow viewer access +} +``` + +To view an example token, you can paste the following token into the [jwt.io debugger](https://jwt.io/#token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NTA4MTM5NDAsImV4cCI6MTc1MDgxNDU0MH0.hGnLRGO09AXNzMHgHLLz1HJ-9mRfDf-PnOd20w9CQmI): + +``` +eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NTA4MTM5NDAsImV4cCI6MTc1MDgxNDU0MH0.hGnLRGO09AXNzMHgHLLz1HJ-9mRfDf-PnOd20w9CQmI +``` + +It was signed with the following random secret: `d2e166fdda89824a6c493d8a2af7a0754199eff9e38c579cba8783767a44039c`. + +## Enable or disable token security for an alias + +Please refer to the [Enable token security for alias](/theolive/api/channels/enable-token-security-for-alias) and [Disable token security for alias](/theolive/api/channels/disable-token-security-for-alias) API endpoints to manage the token security settings for an alias. + +When enabling for the first time, you have to pass the `key` property in the body. If you disable token security later on, and make it active again, you can omit this property if it should stay the same. + +If you're using the [THEOlive management console](https://console.theo.live), you can navigate to the player details page and select the alias you want to enable/disable token security for. When enabling, please pass the correct shared or public key to use. **Don't forget to confirm your changes by hitting the save button!** + +![Managing token security in the console](../../assets/img/51376b6-token.png) + +## Configuring THEOplayer to pass the necessary headers + +Refer to our platform specific guides for details on how to setup JWT security for your channels and information on any known limitations. + +- [React Native](../../playback/react-native/token-based-security.mdx) +- [Web](../../playback/web/token-based-security.mdx) +- [Android](../../playback/android/token-based-security.mdx) +- [Roku](../../playback/roku/01-token-based-security.mdx) diff --git a/theolive_versioned_docs/version-v1/platform/thumbnails-manifests.mdx b/theolive_versioned_docs/version-v1/platform/thumbnails-manifests.mdx new file mode 100644 index 000000000000..1914153e2051 --- /dev/null +++ b/theolive_versioned_docs/version-v1/platform/thumbnails-manifests.mdx @@ -0,0 +1,47 @@ +--- +sidebar_position: 5 +sidebar_label: Thumbnails and HLS +--- + +# Thumbnails Images and HLS + +Thumbnail images representing what is currently happening in a live stream are available for populating a player poster frame, a scrollable list of available streams, and the like. + +Manifests for HLS fallback of THEOlive streams are available for serving a stream to a device that cannot deploy an OptiView player. + +Both thumbnails and HLS manifests are available from a deterministic URL. + +## Getting Thumbnail Images + +Thumbnails are available as jpeg images with URLs in the following format: + +```text +http://discovery.theo.live/channels//stream/thumbnail.jpeg +``` + +- `channelId` is the identifier of the channel you wish to get the thumbnail for +- There is currently no ability to control the size or compression level of a thumbnail image + +An example thumbnail image and URL for a channel: + +```text +http://discovery.theo.live/channels/ar5c53uzm3si4h4zgkzrju44h/stream/thumbnail.jpeg +``` + +![](http://discovery.theo.live/channels/ar5c53uzm3si4h4zgkzrju44h/stream/thumbnail.jpeg) + +## Getting HLS Manifests + +HLS manifests are available in the following URL format: + +```text +http://discovery.theo.live/channels//stream/main.m3u8 +``` + +- `channelId` is the identifier of the channel you wish to get the HLS manifest for + +An example HLS manifest URL for a channel: + +```text +http://discovery.theo.live/channels/ar5c53uzm3si4h4zgkzrju44h/stream/main.m3u8 +``` diff --git a/theolive_versioned_docs/version-v1/platform/viewer-insights.mdx b/theolive_versioned_docs/version-v1/platform/viewer-insights.mdx new file mode 100644 index 000000000000..92919bf63230 --- /dev/null +++ b/theolive_versioned_docs/version-v1/platform/viewer-insights.mdx @@ -0,0 +1,76 @@ +--- +sidebar_position: 7 +--- + +# Viewer Insights + +## Easily monitor and analyze viewer behavior of your live stream + +Curious about who's watching your live stream in real time—and where they're located? Want to track when viewers join or leave your stream? These are just a few of the valuable viewer insights you can access to better understand audience behavior and optimize future streams.THEOlive provides detailed viewer insights for every user. + +This guide explains the types of viewer insights available for your THEOlive channel and shows you where to find them in the platform. + +## How to access viewer insights + +Viewer insights are available for each channel and can be accessed from your channel page. +To view them, go to the _Details_ tab and click on _Viewer Insights_. The screenshot below highlights where to find this option. + +Each channel has its own dedicated viewer insights page. If you're running multiple channels at the same time (including any failover channels), you'll need to repeat this process for each one individually. + +![](../assets/img/e409065-where-insights3.PNG 'insights location') + +## Analyzing viewer insights + +The viewer insights page of your channel includes: + +- Main channel information +- Viewer sessions +- Viewer latency +- Viewer locations +- Top browser and operating systems + +:::warning[Must use THEOlive in THEOplayer to receive viewer insights] + +Viewer insights will only work if you are using THEOlive inside a THEOplayer. Please refer to [this guide](../playback/web/getting-started.mdx) for implementation details. + +::: + +### Main channel information + +The top section displays key information about your channel, including the **channel ID**, channel **name**, and current **status**. This helps you confirm that you're viewing the correct channel data and whether the stream is currently live. + +At the bottom of this section, you’ll find a selector to choose the **period** for the viewer insights graphs. You can choose from several time periods—ranging from _Last hour_ to _Last 30 days_. The data shown in the sections below will adjust based on the selected time range. + +![](../assets/img/5513864-1.viewer_insights.PNG 'viewer insights') + +### Viewer sessions + +This graph displays the number of concurrent viewer sessions during the selected time period. It also highlights the current number of active sessions, giving you real-time insight into how many viewers are watching your live stream at any given moment. + +![](../assets/img/7918a6d-viewer-panel.png 'viewer panel') + +### Viewer latency + +When interactivity matters, ultra-low latency is crucial. + +The next graph displays the viewer latency over the selected time period, showing the percentage of viewers who experienced a specific median latency value. For example, the graph may indicate that most viewers had a latency between 550ms and 950ms, with an overall median latency of 834ms. This helps you assess how closely your stream approaches real-time delivery. + +![](../assets/img/e631989-latency-panel2.png 'latency panel') + +### Viewer locations + +Want to know where your viewers are tuning in from? The next table displays the geographic distribution of your viewers, showing the cities or locations they connected from and the number of connections per location. + +You can sort the table by any column (in ascending or descending order) and adjust the number of rows displayed per page to better explore the data. + +![](../assets/img/71ca1fd-platform-panel1.png 'platform panel') + +### Top browser and operating systems + +Curious about how your viewers are watching your stream—on mobile, desktop, or other platforms? + +The final table on the Viewer Insights page breaks down viewership by browser, browser version, operating system, and OS version. This helps you understand what devices and environments your audience is using. + +You can sort the table by browser, operating system, or session count (ascending or descending), and adjust the number of rows displayed per page to suit your needs. + +![](../assets/img/230b3c5-platform-panel2.png 'platform panel') diff --git a/theolive_versioned_docs/version-v1/platform/viewer-tracking.mdx b/theolive_versioned_docs/version-v1/platform/viewer-tracking.mdx new file mode 100644 index 000000000000..8c42c07db624 --- /dev/null +++ b/theolive_versioned_docs/version-v1/platform/viewer-tracking.mdx @@ -0,0 +1,59 @@ +--- +sidebar_position: 7 +sidebar_label: Viewer Tracking +title: Viewer Tracking +--- + +import CalloutPremiumFeature from '../callouts/_premium_feature.md'; + + + +# Tracking Viewers + +With THEOlive, you can syndicate content through multiple distribution partners while utilizing the same channel, or alternatively track different groups through aliases. This can be helpful for aggregating viewing and billing data for a group of viewers. + +Additionally, when using the advanced reporting feature, you might want to assign tracking metadata to individual viewers to post-process later in your data and BI analysis tools. This is all possible with our viewer tracking workflows. + +## Tracking Workflow + +The following is an **example workflow** for setting up stream tracking: + +1. Create a THEOlive channel +1. Enable [_Token Security_](security/token-based-security.mdx) on the channel or alias +1. When you create your self-signed token, add one or both of the following parameters to a `streaming` object in the `payload` of your JWT: + - **trackingId**: Groups viewers of the same channel, allows you to get the aggregated bandwidth usage of all viewers. This is useful for billing a single channel or alias if you use multiple distribution partners and want aggregated billing metrics back or viewer reports for groups of viewers. The maximum size is 128 characters + - **customViewerData** : Access the bandwidth consumption of each viewer for analytics purposes and passthrough metadata from your CMS for a viewer and be able to retrieve it in a viewer report. This data is not parsed by our system and can be a series of key-value pairs for you to extract later. The maximum size is 1024 characters +1. Pass the JWT through to the player as described in the [_Token Security_](security/token-based-security.mdx) section +1. To get _Advanced Reports_, including user-reports, please contact your Dolby representative for access. + +_Note: Either or both `trackingId` and/or `customViewerData` may be used depending on what kind of tracking you need to achieve._ + +To put it all together, here is an example `payload` for a JWT that includes sample `trackingId` and `customViewerData`: + +```json +{ + "streaming": { + "tracking": { + "trackingId": "groupAbc" + }, + "customViewerData": "user=user123;appVersion=x.y.x", + "tokenType": "Subscribe" + }, + "iat": 1750813271, + "exp": 1750813871 // required for the token to be valid +} +``` + +Here is the JWT that is used to generate this token, you can paste it into [jwt.io](https://jwt.io/#token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdHJlYW1pbmciOnsidHJhY2tpbmciOnsidHJhY2tpbmdJZCI6Imdyb3VwQWJjIn0sImN1c3RvbVZpZXdlckRhdGEiOiJ1c2VyPXVzZXIxMjM7YXBwVmVyc2lvbj14LnkueCIsInRva2VuVHlwZSI6IlN1YnNjcmliZSJ9LCJpYXQiOjE3NTA4MTMyNzEsImV4cCI6MTc1MDgxMzg3MX0.OvIZAvs6XL4KQ8YTtIdjdJNZ5oS6Jkosj3mq274gdrw). + +```text +eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdHJlYW1pbmciOnsidHJhY2tpbmciOnsidHJhY2tpbmdJZCI6Imdyb3VwQWJjIn0sImN1c3RvbVZpZXdlckRhdGEiOiJ1c2VyPXVzZXIxMjM7YXBwVmVyc2lvbj14LnkueCIsInRva2VuVHlwZSI6IlN1YnNjcmliZSJ9LCJpYXQiOjE3NTA4MTMyNzEsImV4cCI6MTc1MDgxMzg3MX0.OvIZAvs6XL4KQ8YTtIdjdJNZ5oS6Jkosj3mq274gdrw +``` + +To see the validation tool validate the token, insert the random secret used to sign the token: `d2e166fdda89824a6c493d8a2af7a0754199eff9e38c579cba8783767a44039c`. + +### Notes + +- Tracking can be used independently of secure channels. You can pass the same payload parameters in a JWT, however, we require that the token is "valid". This means that the required date fields _must_ be valid or the token will be ignored. If a channel does not have token security enabled, however, be aware that anyone can view the channel with or without a jwt token. If secure channels are not enabled, the signature is not validated, so there is a risk that a user _could_ change the values +- If you are combining our OptiView real-time (Millicast) streaming solution and our live streaming solution (THEOlive), you may use the _secret_ from the Millicast subscriber token as the secret you provide to THEOlive and you can use the same JWTs across both streaming products +- `tokenType` should be set to `Subscribe` diff --git a/theolive_versioned_docs/version-v1/playback/android/_category_.json b/theolive_versioned_docs/version-v1/playback/android/_category_.json new file mode 100644 index 000000000000..cc5eade20799 --- /dev/null +++ b/theolive_versioned_docs/version-v1/playback/android/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "Android", + "description": "Start with THEOlive on Android smartphones, tablets and TVs.", + "position": 2, + "customProps": { + "icon": "android" + } +} diff --git a/theolive_versioned_docs/version-v1/playback/android/getting-started.mdx b/theolive_versioned_docs/version-v1/playback/android/getting-started.mdx new file mode 100644 index 000000000000..bbc876ce8648 --- /dev/null +++ b/theolive_versioned_docs/version-v1/playback/android/getting-started.mdx @@ -0,0 +1,153 @@ +--- +sidebar_position: 1 +--- + +# Getting started with THEOlive on Android + +To begin with the Dolby OptiView platform please review our guide for getting started with [OptiView Streaming](../../getting-started.mdx). + +### Installing the THEOplayer for Android + +1. Support for THEOlive comes out of the box with the THEOplayer for Android. Please follow [this guide for installing the Player SDK](/theoplayer/getting-started/sdks/android/getting-started/) for Android development. + +2. Once the Player is installed, continue following the guide for setting up the player. Please note that THEOplayer licenses can be found for streaming customers [here](theolive/getting-started.mdx#obtaining-a-player-license-for-theolive) in the THEOlive dashboard. + +3. With the player installed and set up with a valid license, you can now import the `THEOliveSource` object from the SDK: + +```Kotlin +import com.theoplayer.android.api.theolive.TheoLiveSource +``` + +Rather than set your Player `source` as a manifest as you would for a HLS stream, you can now instead set it as a `TheoLiveSource` including your [channel alias](../../platform/multi-channel.md): + +```Kotlin +theoPlayer.source = SourceDescription + .Builder( + TheoLiveSource( + src = "YOUR_THEOLIVE_CHANNEL_ALIAS" + ) + ) + .build() +``` + +For testing, you can use this HESP demo source: `ar5c53uzm3si4h4zgkzrju44h` which the OptiView team [keeps live 24/7](https://demo.theo.live/?channel=ar5c53uzm3si4h4zgkzrju44h). + +From here, your THEOlive source should be ready to playback in THEOplayer. + +### Adding Player Controls + +At this stage in implementation, you should have a THEOlive stream playing within your Android app. The Player SDK provides functionality for controlling stream playback which can be extended to users in the form of controls or buttons. The platform also supports an [Open Video UI for the Android SDK](pathname:///open-video-ui/android/getting-started), which provides a component library for advanced styling and control of UI components. + +#### 1. Adding Play/Pause Controls + +To add a play/pause button to your app, you’ll first need to create a button. This could be done via an XML layout file, for example: + +```xml +