audience-webplayer-sdk

audience-webplayer-sdk is a powerful, event-driven library designed to simplify the integration and management of audience video streaming capabilities within web applications. It allows developers to seamlessly connect to and control video streams, leveraging a modern API to manage playback, volume control, and state management.

If you are a streamer, set up your RTMP channel by visiting the RTMP settings page at (https://stream.meta-audience.com/:your-app-id). Please contact us at service.xr-rd@kkcompany.com to apply for an app-id.

audience-webplayer-sdk 是一款強大的事件驅動庫，簡化在網頁應用程式中整合和管理 audience 影片串流功能。使開發者無縫連接和控制直播串流，透過 API 來管理播放、音量控制和狀態管理。

如果你是 Streamer，請透過 RTMP 設定頁面 (https://stream.meta-audience.com/:your-app-id) 設置 RTMP 頻道。請向 service.xr-rd@kkcompany.com 聯繫我們申請 app-id。

Key Features

• Play video streams directly in web environments.
• Easy integration with audience streaming services.
• Event-Driven Architecture: Respond to changes in playback, volume, and connection status with custom event listeners.
• Flexible Connection Handling: Connect and disconnect from video streams with robust state management.
• Interactive Controls: Control playback, adjust volume, and update the channel dynamically.
• 在網頁環境中直接播放直播串流。
• 與 audience 串流服務的輕鬆整合。
• 事件驅動架構：通過自定義事件監聽器響應播放、音量和連接狀態的變化。
• 靈活的連接處理：通過健全的狀態管理連接和斷開直播串流。
• 互動控制：控制播放，調整音量，並動態更新頻道。

Quick Start

Streamer

To start streaming using the audience-webplayer-sdk, follow these steps:

For detailed operations, please see this video.

1. Register an Account

   • Visit our official website meta-audience.com and register an account.

2. Access RTMP Settings

   • Navigate to the RTMP settings page at stream.meta-audience.com/:your-app-id. Replace :your-app-id with your actual app-id.
   • If you don't have an app-id, please contact us at service.xr-rd@kkcompany.com to apply for one.

3. Login

   • Log in with your newly created account credentials.

4. Create a Channel

   • Once logged in, proceed to create a new channel where you will host your streams.
   • In the Stream Settings section:
     • Video Mode: Please select 2D Flat, as the SDK currently only supports this type. If any other type is chosen, the SDK will automatically default to 2D Flat.
     • Expired Time(s): The maximum value is 2592000 (30 days). If you need to keep the channel open longer, please contact us at service.xr-rd@kkcompany.com.

5. Obtain Stream Credentials

   • After creating your channel, copy the Stream URL and Stream Key from the channel settings. These will be used to configure your streaming software.

6. Open OBS

   • Launch Open Broadcaster Software (OBS) or any other streaming software you prefer.

7. Setup Streaming

   • In OBS, go to settings and set up your streaming configuration by entering the copied Stream URL and Stream Key. Ensure that your video and audio encoding settings are optimized for live streaming.

8. Start Streaming

   • After setting up your stream, go back to the main OBS screen and click the "Start Streaming" button. You should now be live!

Ensure your internet connection is stable throughout to maintain a high-quality stream.

---

要使用 audience-webplayer-sdk 開始串流，請按照以下步驟操作：

如需詳細操作，請參閱 video。

1. 註冊帳號

   • 請至我們的官方網站 meta-audience.com 並註冊一個帳號。

2. 訪問 RTMP 設置

   • 開啟 RTMP 設置頁面 stream.meta-audience.com/:your-app-id。將 :your-app-id 替換為實際的 app-id。
   • 如果沒有 app-id，請通過 service.xr-rd@kkcompany.com 聯繫我們申請一個。

3. 登入

   • 使用新註冊的號登入。

4. 創建一個頻道

   • 登入後，繼續創建一個新的頻道來推送你的內容。
   • 在 Stream Settings 部分：
     • Video Mode：請選擇 2D Flat，因為 SDK 目前只支援這種類型。如果選擇了其他類型，SDK 將自動默認為 2D Flat。
     • **Expired Time(s)**：最大值為 2592000（30 天）。如果需要保持頻道開放更長時間，請透過 service.xr-rd@kkcompany.com 聯繫我們。

5. 獲取串流憑證

   • 創建頻道後，從頻道設置中複製 Stream URL 和 Stream Key。這些將用於設定你的串流軟體。

6. 打開 OBS

   • 啟動 Open Broadcaster Software (OBS) 或喜歡的任何其他串流軟體。

7. 設置串流

   • 在 OBS 中，進入設置並通過輸入複製的 Stream URL 和 Stream Key 來設置串流設定

8. 開始串流

   • 設置好串流後，回到 OBS 主畫面並點擊“開始串流”按鈕。現在應該已經開始直播了！

請確保網路連接穩定以保持高品質的串流。

Viewer

Installation

You can install audience-webplayer-sdk using npm:

使用 npm 安裝 audience-webplayer-sdk：

npm install audience-webplayer-sdk
Copy

Or using yarn:

yarn add audience-webplayer-sdk
Copy

Basic Usage

Here's a basic example of how to use the audience-webplayer-sdk to embed a video player, connect to a channel, and handle events:

這是使用 audience-webplayer-sdk 嵌入影片播放器、連接到頻道並處理事件的基本範例：

Configuration

To begin using the audience-webplayer-sdk, you must first initialize the SDK by setting up your account configuration. This is done through the Initialize.set() function, which configures your session and retrieves an initial channel table from your account. The channel table includes details about all available channels that you can connect to.
Here's how you can configure and initialize the SDK:

要開始使用 audience-webplayer-sdk，必須先設置帳號設定來初始化 SDK。使用 Initialize.set() 進行設定後會回傳頻道清單(channelTable)。頻道清單包括所有可用頻道的詳細資訊。
這是設定和初始化 SDK 的方式：

import { WebPlayer, WebPlayerEvents, Initialize } from 'audience-webplayer-sdk';

// Specify the account email to retrieve associated channels
const accountEmail = 'your-email@domain.com';  // Replace with your account email
const useLowLatency = false;  // (Optional) Set this to your desired value

async function initializeSdk() {
    try {
        const { channelTable } = await Initialize.set({ account: accountEmail, lowLatency: useLowLatency });
        console.log('Initialization successful, retrieved channel table:', channelTable);
        return channelTable;
    } catch (error) {
        console.error('Failed to initialize the SDK:', error);
    }
}
Copy

Connecting to a Channel

Connecting to a video stream or channel is a key functionality of the audience-webplayer-sdk. This section describes how to establish a connection to a specific channel using the WebPlayer instance.
Below is a step-by-step example of how to connect to a channel using a previously initialized WebPlayer instance. This example assumes that you have a valid channel ID obtained from your channel table after initialization.

連接到直播串流與頻道是 audience-webplayer-sdk 的關鍵功能。這裡描述如何使用 WebPlayer 建立實例以及如何連接到特定的頻道。
以下是使用先前初始化的 WebPlayer 實例連接到頻道的逐步範例。此範例假設在初始化後從的頻道表中獲得了有效的頻道 ID。

// Obtain a reference to your video element in the HTML
const videoElement = document.getElementById('myVideoPlayer');

// Create a new WebPlayer instance with the video element
const player = new WebPlayer({
    videoElement: videoElement
});

// Function to connect to a channel
async function connectToChannel(channelId) {
    try {
        const channel = await player.connect(channelId);
        console.log('Connected to channel:', channel.name);
    } catch (error) {
        console.error('Connection failed:', error);
    }
}

// Example usage: Assuming 'channelTable' is obtained from the 'initialize' function
initialize().then(channelTable => {
    const channelId = Object.values(channelTable)[0].id;  // Accessing the first channel ID
    connectToChannel(channelId).then(() => {
        console.log('Connection established successfully.');
    });
});
Copy

Event Handling

Listen to events such as volume changes, play, pause, and channel updates:

監聽事件，如音量變化、播放、暫停和頻道更新：

player.event.on(WebPlayerEvents.VOLUME_CHANGE, (volume) => {
    console.log('Volume changed to:', volume);
});

player.event.on(WebPlayerEvents.MUTE_CHANGE, (mute) => {
    console.log('mute state changed to:', mute);
});

player.event.on(WebPlayerEvents.PLAY, () => {
    console.log('Playback started');
});

player.event.on(WebPlayerEvents.PAUSE, () => {
    console.log('Playback paused');
});

player.event.on(WebPlayerEvents.DISCONNECTED, () => {
    console.log('Playback disconnected');
});

player.event.on(WebPlayerEvents.CONNECTED, () => {
    console.log('Playback connected');
});

player.event.on(WebPlayerEvents.CHANNEL_UPDATE, (channel) => {
    console.log('Channel updated:', channel.name);
});

Copy

Fullscreen Support

Trigger fullscreen mode on user interaction:

在使用者互動時觸發全螢幕模式：

document.getElementById('fullscreenButton').addEventListener('click', async () => {
    await player.requestFullscreen();
    console.log('Fullscreen mode activated');
});

Copy

Handling Channel Updates

To handle updates to the channel's viewer count or other attributes, you can listen for the CHANNEL_UPDATE event. This event is emitted every 30 seconds.

要處理頻道觀看者數量或其他屬性的更新，可以監聽 CHANNEL_UPDATE 事件。此事件每30秒發出一次。

player.event.on(WebPlayerEvents.CHANNEL_UPDATE, (channel) => {
    console.log('Channel updated:', channel.name);
    console.log('New viewer count:', channel.viewCount);
    // Update the UI with the new viewer count
    document.getElementById('viewerCountDisplay').textContent = `Viewers: ${channel.viewCount}`;
});

Copy

In this example, the CHANNEL_UPDATE event listener logs the updated channel information and updates the displayed viewer count on the webpage.

在此範例中，CHANNEL_UPDATE 事件監聽器會記錄更新的頻道資訊並在網頁上更新顯示的觀看者數量。

Disconnecting from a Channel

Properly disconnecting from a video stream is crucial for maintaining application performance and freeing up resources. The audience-webplayer-sdk provides a straightforward method to safely disconnect your WebPlayer instance from the current channel.

適當地斷開直播串流連接對於維護應用程式效能和釋放資源至關重要。audience-webplayer-sdk 提供了一種直接的方法，以安全地斷開 WebPlayer 實例與當前頻道的連接。

player.disconnect()
Copy

Online Resources

• Online Player example
• API documents
• RTMP setting page (https://stream.meta-audience.com/:your-app-id)

Contact Us

For any inquiries, please feel free to email us at:

service.xr-rd@kkcompany.com

---