在應用程式中內嵌 Azure AI Video Indexer 小工具

2025-05-30

本文說明如何將 Azure AI Video Indexer 小工具內嵌到應用程式中。 Azure AI 影片索引器支援將三種類型的小工具內嵌至您的應用程式： 深入解析、 播放機和 編輯器。

Insights 小工具包含從影片索引程式擷取的所有視覺見解。 Insights 小工具支援下列選擇性 URL 參數：

名稱	定義	描述
`widgets`	以逗號分隔的字串	您可以控制要呈現的分析洞見。範例：`https://www.videoindexer.ai/embed/insights/<accountId>/<videoId>/?widgets=people,keywords` 只會呈現人員和關鍵字的 UI 分析。可用選項：`people`、`keywords`、`audioEffects`、`labels`、`sentiments`、`emotions`、`topics`、`keyframes`、`transcript`、`ocr`、`speakers`、`scenes`、`spokenLanguage`、`observedPeople`、`namedEntities`、`detectedObjects`。
`controls`	以逗號分隔的字串	可讓您控制您想要呈現的控制項。範例：`https://www.videoindexer.ai/embed/insights/<accountId>/<videoId>/?controls=search,download` 只會轉譯搜尋選項和下載按鈕。可用選項：`search`、`download`、`presets`、`language`。
`language`	簡短語言代碼 (語言名稱)	控制洞察語言。範例: `https://www.videoindexer.ai/embed/insights/<accountId>/<videoId>/?language=es-es` 或 `https://www.videoindexer.ai/embed/insights/<accountId>/<videoId>/?language=spanish`
`locale`	簡短語言代碼	控制 UI 的語言。預設值是 `en`。範例：`locale=de`。
`tab`	預設選取的索引標籤	控制預設呈現的深入解析標籤。範例：`tab=timeline` 會在選取時程表索引標籤的情況下，呈現相關見解。
`search`	字串	可讓您控制初始搜尋字詞。範例：`https://www.videoindexer.ai/embed/insights/<accountId>/<videoId>/?search=azure` 呈現根據關鍵字 Azure 篩選出的洞察。
`sort`	以逗號分隔的字串	可讓您控制洞察的排序。每個排序都包含三個值：與『_『連接的小工具名稱、屬性和順序 `sort=name_property_order` 可用選項： widgets：`keywords`、`audioEffects`、`labels`、`sentiments`、`emotions`、`keyframes`、`scenes`、`namedEntities`和 `spokenLanguage`。屬性：`startTime`、`endTime`、`seenDuration`、`name`和 `ID`。順序：升序和降序。範例：`https://www.videoindexer.ai/embed/insights/<accountId>/<videoId>/?sort=labels_id_asc,keywords_name_desc` 會以遞增順序轉譯依識別碼排序的標籤，並以遞減順序轉譯依名稱排序的關鍵字。
`location`		`location` 參數必須包含在內嵌連結中;請參閱如何取得區域的名稱。如果您的帳戶正在預覽中，則應使用 `trial` 作為位置值。 `trial` 是 `location` 參數的預設值。

您可以使用播放器小工具，使用自適性位元速來串流視訊。播放器小工具支援下列選擇性 URL 參數。

名稱	定義	描述
`t`	開始後的秒數	可讓播放器從指定的時間點開始播放。範例：`t=60`。
`captions`	語言代碼/語言代碼陣列	在小工具載入期間，擷取指定語言的字幕，以便在 [字幕] 功能表中使用。範例：`captions=en-US`、`captions=en-US,es-ES`
`showCaptions`	布林值	可讓播放器載入已啟用的標題。範例：`showCaptions=true`。
`type`		啟動音訊播放器面板 (已移除影片部分)。範例：`type=audio`。
`autoplay`	布林值	指出播放器是否應在影片載入後開始播放。預設值是 `true`。範例：`autoplay=false`。使用自動播放的能力受限於使用的網頁瀏覽器原則： Firefox、 Google Chrome、 macOS WebKit
`language`/`locale`	語言代碼	控制播放器語言。預設值是 `en-US`。範例：`language=de-DE`。
`location`		`location` 參數必須包含在內嵌連結中;請參閱如何取得區域的名稱。如果您的帳戶正在預覽中，則應使用 `trial` 作為位置值。 `trial` 是 `location` 參數的預設值。
`boundingBoxes`	周框方塊的陣列。選項：人員 (臉部)、觀察到的人員和偵測到的物件。以逗號（，）分隔值。	控制內嵌播放器時的開啟/關閉邊界框選項。所有提及的選項都已開啟。範例: `boundingBoxes=observedPeople,people,detectedObjects` 預設值是 `boundingBoxes=observedPeople,detectedObjects` (只有觀察到的人員和偵測到的物件周框方塊會開啟)。

您可以使用編輯器小工具來建立新專案及管理影片的深入解析。編輯器小工具支援下列選擇性 URL 參數。

名稱	定義	描述
`accessToken`^*	字串	提供僅限於用來嵌入小工具的帳戶中的影片存取權。編輯器小工具需要 `accessToken` 參數。
`language`	語言代碼	控制播放器語言。預設值是 `en-US`。範例：`language=de-DE`。
`locale`	簡短語言代碼	控制洞察語言。預設值是 `en`。範例：`language=de`。
`location`		參數 `location` 必須包含在內嵌連結中。請參閱如何取得區域的名稱。如果您的帳戶正在預覽中，則應使用 `trial` 作為位置值。 `trial` 是 `location` 參數的預設值。

^*所有者應謹慎提供accessToken。

內嵌影片

本節討論如何使用網站或將 URL 手動組合至應用程式中，來內嵌影片。

參數 location 必須包含在內嵌連結中。請參閱如何取得區域的名稱。如果您的帳戶正在預覽中，則應使用 trial 作為位置值。 trial 是 location 參數的預設值。例如： https://www.videoindexer.ai/accounts/00000000-0000-0000-0000-000000000000/videos/b2b2c74b8e/?location=trial 。

網站體驗

若要內嵌影片，請按照以下步驟在網站中嵌入影片。

登入 Azure AI Video Indexer 網站。
選取您想要使用的影片，然後按 [播放]。
選取您想要的小工具類型 (深入解析、播放器或編輯器)。
選取 </> 內嵌。
在 [分享與內嵌] 對話框中，複製內嵌代碼。
將程式碼新增至應用程式。

注意

共用 Player 或 Insights 小工具的連結時會包含存取權杖，並將只讀權限授予您的帳戶。

手動組合 URL

公開影片

您可以組合 URL 以內嵌公用影片，如下所示：

https://www.videoindexer.ai/embed/[insights | player]/<accountId>/<videoId>

私人影片

若要內嵌私人影片，您必須傳遞存取權杖 (在 iframe 的屬性中使用src取得影片存取權杖：

https://www.videoindexer.ai/embed/[insights | player]/<accountId>/<videoId>/?accessToken=<accessToken>

提供編輯洞察能力功能

若要在內嵌小工具中提供編輯深入解析功能，您必須傳遞包含編輯權限的存取權杖。使用取得影片存取令牌的 API 要求 &allowEdit=true。

小工具互動

Insights 小工具可以與應用程式上的影片互動。本節說明如何進行此互動。

流程概觀

當您編輯文字記錄時，即會發生下列流程：

您在時間軸中編輯文字稿。
Azure AI Video Indexer 會取得這些更新，並從語言模型中的文字記錄編輯儲存這些更新。
字幕隨即更新：
- 如果您使用 Azure AI 影片索引機播放器小工具 - 它會自動更新。
- 如果您使用的是外部播放程式 - 您可以透過 取得影片字幕 的 API 呼叫獲得新的字幕檔案。

跨來源通訊

若要啟用 Azure AI Video Indexer 小工具並與其他元件互動：

使用跨來源通訊 HTML5 方法 postMessage。
驗證來自 VideoIndexer.ai 原始來源的訊息。

如果您實作自己的播放機程序代碼，並與 Insights 小工具整合，則您必須負責驗證來自 VideoIndexer.ai 訊息的來源。

在您的應用程式或部落格中內嵌小工具 (建議)

本節說明如何達成兩個 Azure AI 影片索引器小工具之間的互動。當用戶選取您應用程式上的深入解析控件時，玩家會跳到相關時刻。

複製播放器小工具的內嵌程式碼。
複製 Insights 內嵌程式代碼。
新增中繼程序檔案以處理兩個小工具之間的通訊：
<script src="https://aka.ms/vi-mediator-file"></script>

現在，當使用者選取您應用程式上的深入解析控制項時，播放器即會跳到相關的時間點。

如需詳細資訊，請參閱 Azure AI Video Indexer - 內嵌兩個小工具示範。

如果您使用視訊索引機播放器以外的視訊播放程式，您必須手動操作視訊播放程式以達成通訊。

插入影片播放器。

例如，標準 HTML5 播放器：

<video id="vid1" width="640" height="360" controls autoplay preload>
   <source src="//vi-static-prod-gdh6d4ggexcmgua5.b01.azurefd.net/public/Microsoft%20HoloLens-%20RoboRaid.mp4" type="video/mp4" /> 
   Your browser does not support the video tag.
</video>

內嵌 Insights 小工具。

透過監聽「message」事件，為您的播放器實現通訊功能。例如：

<script>

    (function(){
    // Reference your player instance.
    var playerInstance = document.getElementById('vid1');

    function jumpTo(evt) {
      var origin = evt.origin || evt.originalEvent.origin;

      // Validate that the event comes from the videoindexer domain.
      if ((origin === "https://www.videoindexer.ai") && evt.data.time !== undefined){

        // Call your player's "jumpTo" implementation.
        playerInstance.currentTime = evt.data.time;

        // Confirm the arrival to us.
        if ('postMessage' in window) {
          evt.source.postMessage({confirm: true, time: evt.data.time}, origin);
        }
      }
    }

    // Listen to the message event.
    window.addEventListener("message", jumpTo, false);

    }())    

</script>

如需詳細資訊，請參閱影片索引機播放機 + VI 深入解析示範。

自訂內嵌小工具

您可以選擇您想要的深入解析類型。若要這樣做，請將它們指定為下列URL參數的值。它會新增至您從 API 或 Azure AI 影片索引器網站取得的內嵌程式代碼中： &widgets=<list of wanted widgets>。

可能的值列於此處。

例如，如果您想要內嵌僅包含人員和關鍵詞深入解析的小工具，iframe 內嵌 URL 會類似：

https://www.videoindexer.ai/embed/insights/<accountId>/<videoId>/?widgets=people,keywords

iframe 視窗的標題也可透過將 &title=<YourTitle> 提供給 iframe URL 來自訂。 (其會自訂 HTML <title> 值)。

例如，如果您想要為iframe視窗提供標題 MyInsights，則URL會類似：

https://www.videoindexer.ai/embed/insights/<accountId>/<videoId>/?title=MyInsights

請注意，只有您需要在新視窗中開啟深入解析時，才適用此選項。

在內嵌 Azure AI Video Indexer 播放器時，您可以指定 iframe 的大小來選擇播放器的大小。

例如：

> [!VIDEO https://www.videoindexer.ai/embed/player/<accountId>/<videoId>/]>/<videoId>/" frameborder="0" allowfullscreen />

根據預設，Azure AI 影片索引器播放器會根據影片的文字記錄自動生成字幕。文字記錄會從影片中擷取，其中包含上傳影片時選取的來源語言。

如果您想要使用不同的語言內嵌，則可以將 &captions=<Language Code> 新增至內嵌播放器 URL。如果您想要依預設顯示標題，您可以傳遞 &showCaptions=true。

然後內嵌 URL 類似：

https://www.videoindexer.ai/embed/player/<accountId>/<videoId>/?captions=en-us

自動播放

根據預設，播放程式會開始播放影片。您可以選擇不執行某項操作，方法是將 &autoplay=false 傳遞到之前的內嵌 URL。

程式碼範例

請參閱程式碼範例存放庫，其中包含 Azure AI Video Indexer API 和小工具範例：

檔案/資料夾	描述
`control-vi-embedded-player`	內嵌 VI 播放器並從外部加以控制。
`custom-index-location`	從自訂外部位置（可以是客戶的 Blob）內嵌 VI 資訊洞察。
`embed-both-insights`	VI Insights 播放器和深入解析的基本用法。
`customize-the-widgets`	使用自訂選項內嵌 VI 小工具。
`embed-both-widgets`	內嵌 VI 播放器和分析功能，並在它們之間進行通訊。
`url-generator`	根據使用者指定的選項產生小工具自訂的內嵌 URL。
`html5-player`	使用預設的 HTML5 影片播放器內嵌 VI 洞察。

支援的瀏覽器

如需詳細資訊，請參閱支援的瀏覽器。

使用 npmjs 套件在應用程式中內嵌和自訂 Azure AI Video Indexer 小工具

使用我們的 @azure/video-analyzer-for-media-widgets 套件，您可以將深入解析小工具新增至您的應用程式，並根據您的需求加以自訂。

與其新增 iframe 元素來內嵌深入解析小工具，透過這個新套件，您可以輕鬆地在我們的小工具之間進行內嵌和通訊。在此套件中，您可全面自訂小工具，一切都在同一處完成。

如需詳細資訊，請參閱 GitHub。

此外，請參閱 Azure AI Video Indexer CodePen。

共用方式為

在應用程式中內嵌 Azure AI Video Indexer 小工具

小工具類型

洞察小工具

播放器小工具

編輯器小工具