即時 API:建立點播剪輯

在本主題中,您將學習如何使用 Live API 從直播流中創建視頻點播 (VOD) 剪輯。

概覽

剪輯是從實時流中提取的視頻。可以將它們發送到S3存儲桶,FTP站點或Video Cloud帳戶。該剪輯將創建為MP4視頻,並且在所有情況下都是發送到目的地的內容。如果是Video Cloud,MP4將由攝取系統進行轉碼,為視頻創建哪種格式的呈現將取決於所使用的攝取配置文件。

剪輯的定義是使用/vods端點。

剪輯可以通過幾種方式創建:

  • stream_start_timecode和/或stream_end_timecode在SMPTE時間碼中為直播事件定義的- 請注意,這要求編碼器發送時間碼信息
  • start_time和/或end_time相對於開始時間(stream_start_time)的整個直播活動
  • start_time和/或end_time以紀元(Unix)時間定義(以秒為單位)
  • duration
  • Live API 和 Live Module 都支持從加密或受 DRM 保護的作業創建剪輯。

注意事項

  1. 為了盡可能快地使剪輯可用,首先創建了一個段精確的剪輯,然後在可用時立即將其替換為幀精確的剪輯。
  2. 如果指定duration,結果片段將如下所示:
    • 如果作業處於活動狀態並且仍然有效:(請求時間-持續時間)至(請求時間)
    • 如果作業完成:(finished_at -持續時間)至(finished_at
  3. 如果同時指定start_timeend_time
    • 如果工作處於活動狀態並且仍然有效:只要大紀元時間窗口完全落在created_at和請求時間,將製作剪輯
    • 如果作業完成:只要Epoch時間窗口完全落在created_atfinished_at,將製作剪輯
  4. 直播視頻片段使用智囊團將不包含廣告。
  5. 活動結束後最多7天即可創建剪輯。對於SEP,它們可以創建到下一次激活或7天(以較短者為準)。
  6. VOD API不會在流中添加任何內容。如果在300秒長的實時流中指定350,則輸出將為300秒長。
  7. 您無需使用啟用DVR的直播就可以進行剪輯,因為直播是在廣播時存儲的,並且可以在事件結束後的7天內立即使用。
  8. Brightcove Live剪輯只會產生與高分辨率輸出相同分辨率的剪輯。它不會匹配源輸入分辨率(除非與最高分辨率輸出相同)。

剪輯也可以發送到多個目的地:

  • 一種Video Cloud帳戶
  • FTP服務器
  • 一個S3存儲桶

指定剪輯時,輸出必須包含要么一種url目的地要么一種videocloud對象,以詳細介紹視頻的創建和片段的攝取Video Cloud

注意:剪輯可以在直播流運行時創建。為此,您需要以紀元時間或相對於時間定義片段的開始和結束時間開始直播時間。

身份證明

如果要將剪輯發送到的目標位置需要訪問憑據,則可以使用Live API的憑據操作來創建這些憑據。看到管理Live API的憑據更多細節。

端點

剪輯是通過發送POST請求:

https://api.bcovlive.io/v1/vods

要求正文- Video Cloud

示例1:相對於流開始的開始/結束時間

要求主體包括開始和結束時間,以及要傳送剪輯片段的詳細資料。以下是一個示例請求主體,它創建一個流的第三分鐘剪輯並將其發送到一個Video Cloud帳戶:

{
  "live_job_id":"PUT-LIVE-JOB-ID-HERE",
  "outputs":[
    {
      "label": "60 secs by stream from min 2 to min 3",
      "stream_start_time": 120,
      "stream_end_time": 180,
      "credentials": "USER_VIDEOCLOUD_CREDENTIAL_LABEL",
      "videocloud": {
        "video": {
        "name": "One Minute Clip",
        "tags": ["live", "clip"]
        },
          "ingest": {
            "capture-images": true
        }
      }
    }
  ]
}

在此示例中,我們將創建一分鐘持續時間的剪輯並將其發送到Video Cloud。我們為剪輯指定了名稱和幾個標籤,但未指定ingest profile進行重新轉碼,以便使用帳戶默認值,並指示Video Cloud在轉碼過程中從剪輯中捕獲縮略圖和海報圖像。

範例2:以大紀元時間開始/結束時間

要求主體包含 Epoch 時間的開始和結束時間,以及有關傳送剪輯片段的詳細資料。以下是一個示例請求主體,它創建一個流的第三分鐘剪輯並將其發送到一個Video Cloud帳戶:

{
  "live_job_id":"PUT-LIVE-JOB-ID-HERE",
    "outputs":[
      {
        "label": "60 secs - epoch time",
        "start_time": 1516652694,
        "end_time": 1516652754,
        "credentials": "USER_VIDEOCLOUD_CREDENTIAL_LABEL",
        "videocloud": {
          "video": {
          "name": "One Minute Clip",
          "tags": ["live", "clip"]
          },
            "ingest": {
            "capture-images": true
        }
      }
    }
  ]
}

在此示例中,我們將在特定的紀元時間(本例中為2018年1月22日格林尼治標準時間08:24:54)創建一分鐘持續時間的剪輯。

示例3:具有相對於流開始的開始時間的持續時間

請求主體包括持續時間和stream_start_time,以及有關將剪輯發送到何處的詳細信息。以下是一個示例請求主體,它創建一個流的第三分鐘剪輯並將其發送到一個Video Cloud帳戶:

{
  "live_job_id":"PUT-LIVE-JOB-ID-HERE",
  "outputs":[
    {
      "label": "60 secs from start time",
      "stream_start_time": 300,
      "duration": 60,
      "credentials": "USER_VIDEOCLOUD_CREDENTIAL_LABEL",
      "videocloud": {
        "video": {
        "name": "One Minute Clip",
        "tags": ["live", "clip"]
        },
        "ingest": {
        "capture-images": true,
        "profile": "valid-ingest-profile-name"
        }
      }
    }
  ]
}

在此示例中,我們將創建一個實時直播開始後5分鐘開始的一分鐘持續時間的剪輯。

示例4:沒有開始或結束時間的持續時間

要求主體包含 Epoch 時間的開始和結束時間,以及有關傳送剪輯片段的詳細資料。以下是一個示例請求主體,它創建一個流的第三分鐘剪輯並將其發送到一個Video Cloud帳戶:

{
  "live_job_id":"PUT-LIVE-JOB-ID-HERE",
  "outputs":[
    {
      "label": "60 secs - duration",
      "duration": 60,
      "credentials": "USER_VIDEOCLOUD_CREDENTIAL_LABEL",
      "videocloud": {
        "video": {
        "name": "One Minute Clip",
        "tags": ["live", "clip"]
        },
        "ingest": {
          "capture-images": true
        }
      },
      "notifications": ["https://myserver.com/api/notification_listener?type=jvod"]
    }
  ]
}

在此示例中,我們將創建一個持續時間為一分鐘的剪輯。由於我們未指定開始時間或結束時間,因此將從實時流的最後60秒開始提取剪輯。

示例5:使用stream_start_timecodestream_end_timecode

請求主體包括HH:MM:SS:FF時間碼中的開始和結束時間/幀,以及有關將剪輯發送到何處的詳細信息。請注意,要使用時間碼,編碼器必須正在發送時間碼。這是一個示例請求正文,它創建了一個流的50分鐘的片段並將其發送到Video Cloud帳戶:

{
  "live_job_id":"PUT-LIVE-JOB-ID-HERE",
  "outputs":[
    {
      "label": "Clipping using Timecode from-01:10:18:15 to-01:11:08:15",
      "stream_start_timecode": "01:10:18:15",
      "stream_end_timecode": "01:11:08:15",
      "credentials": "USER_VIDEOCLOUD_CREDENTIAL_LABEL",
      "videocloud": {
        "video": {
          "name": "Fifty Minute Clip",
          "tags": ["live", "clip"]
        },
        "ingest": {
        "capture-images": true
        }
      }
    },
    "notifications": ["https://myserver.com/api/notification_listener?type=jvod"]
  ]
}

有關將剪輯發送到的一般信息Video Cloud

要查看哪些字段可以包含在videoingest對象,請參閱Dynamic Ingest API Reference

請求正文-S3

請求正文包括開始和結束時間,以及發送剪輯的詳細信息。這是一個示例請求主體,它創建流的第三分鐘的剪輯並將其發送到S3存儲桶:

{
  "live_job_id":"",
  "outputs":[
    {
      "label": "last_30",
      "duration": 30,
      "url": "s3://YOUR_BUCKET_NAME/file_name.mp4",
      "credentials": "s3-credentials",
      "notifications": ["https://myserver.com/api/notification_listener?type=jvod"]
    }
  ],
}

在此示例中,我們將創建一個30秒持續時間的剪輯並將其發送到S3存儲桶。我們提供存儲桶 URL,包括剪輯的文件名,以及一個作為已保存 S3 存儲桶憑據名稱的字符串。

您可以使用 Live API 創建和管理憑據。如需詳細資訊,請參閱下列內容:

請求正文

這是請求正文字段的完整表。

請求主體欄位
欄位 類型 描述
live_job_id 字串

用於創建VOD剪輯的實時流作業的ID。

outputs 物件 []

VOD輸出陣列

outputs.label 字串

輸出標籤

outputs.duration 編號

剪輯的持續時間(以秒為單位)。的duration可以單獨使用以定義由最終片段構成的片段{duration}流的秒數。duration也可以與任何之一stream_start_timestream_end_timestart_timeend_timestream_end_timecode, 要么stream_start_timecode

outputs.stream_start_time 編號

剪輯的開始時間(以秒為單位)相對於實時流的開始時間,stream_start_time必須與要么stream_end_time要么duration

outputs.stream_end_time 編號

剪輯的結束時間(以秒為單位)相對於直播流的開始時間,stream_end_time必須與要么stream_start_time要么duration

outputs.start_time 編號

剪輯的開始時間以紀元(Unix)時間(秒)為單位,start_time必須與要么end_time要么duration

outputs.end_time 編號

剪輯的結束時間,以紀元(Unix)時間(秒)為單位,end_time必須與要么start_time要么duration

outputs.stream_start_timecode 編號

剪輯的開始時間,從流的開始開始,採用SMPTE格式(HH:MM:SS:FF)的時間碼,stream_start_timecode必須與要么stream_end_timecode要么duration

outputs.stream_end_timecode 編號

剪輯的結束時間,從流的末尾開始,採用SMPTE格式(HH:MM:SS:FF)的時間碼,outputs.stream_end_timecode必須與要么stream_start_timecode要么duration

outputs.url 字串

剪輯的目標URL,請注意輸出必須包含要么這個url領域要么一種videocloud定義視頻屬性和攝取選項的對象Video Cloud

outputs.credentials 字串

您的帳戶中為此地址配置的憑據名稱

outputs.videocloud 物件

包含輸入的對象Video Cloud攝取

outputs.videocloud.video 物件

包含輸入的對象Video Cloud視頻對象的創建-請參閱CMS API Reference for creating a video

outputs.videocloud.ingest 物件

包含輸入的對象Video Cloud視頻攝取-請參閱Dynamic Ingest Reference -做包括master字段,因為該信息將由Live API提供。如果未指定提取配置文件,則將使用帳戶默認配置文件。

的視頻字段Video Cloud攝取

CMS API參考更多細節。

視訊欄位
欄位 類型 描述
ad_keys 字串 代表指派給影片之廣告鍵/值配對的字串。鍵/值對被格式化為鍵 = 值,並由 & 符號分隔。例如:"adKeys": "category=sports&live=true"
cue_points 地圖陣列 提示點對應陣列
custom_fields 字段值對映(字符串) 自訂fieldname:value為視頻設置-請注意,該視頻的價值未包含在此地圖中;自定義字段值的最大長度為1024個單字節字符
description 字串;取代舊的簡短描述 視訊的簡短描述 (最大長度:248 個單位元組字元)
economics 字符串,必須是有效的枚舉值之一 可以是「AD_ 支持」(默認)或「免費」
geo 屬性值對的地圖 視訊的地理限制屬性
link 屬性值對的地圖 相關連結屬性的地圖
long_description 字串 完整描述 (最多 5000 個字元)
name 字串 視頻名稱(最大長度:248個單字節字符)需要
offline_enabled 布林值 視訊是否已啟用離線播放
projection 字串 360° 影片的映射投影,例如「等距矩形」
reference_id 字串 使用者指定的 ID,唯一識別視訊,限制為 150 個字元。參照 ID 可以用作外鍵,以在另一個系統中識別此視頻。參考 ID 不應包含空格、逗號或特殊字元。
schedule 屬性值對的地圖 視訊可用性的開始與結束日期時間地圖
state 字串 活動,不活動
tags 標籤陣列 (字串) 指派給視訊的標籤陣列
text_tracks HTML5 風格的文本軌道的數組 指派給視訊的文字軌道 (WebVTT 檔案) 陣列

視頻提示點字段

下表顯示了video.cuepoints

提供點欄位
欄位 類型 描述
id 字串 提示點的系統 ID
force_stop 布林 視訊是否應該停止在提示點
metadata 字串;僅限代碼點 與提示點相關聯的中繼資料字串
name 字串 提示點名稱
time 浮動 從影片開始開始測量的提示點時間 (以秒為單位)
type 字串 提示點類型 ( ADDATA )

視頻地理字段

下表顯示了對video.geo象字段。

地理篩選欄位
欄位 類型 描述
countries 國家代碼字串陣列 允許或不允許播放視頻的國家/地區的ISO 3166 2或4字母代碼列表(https://www.iso.org/obp/ui/)的數組
exclude_countries 布林值 如果為 true,則會將國家陣列視為排除在檢視之外的國家清單
restricted 布林值 此視訊是否已啟用地理篩選功能

下表顯示了對video.link象字段。

連結欄位
欄位 類型 描述
url 字串 相關連結網址
text 字串 相關連結文字

視頻時間表字段

下表顯示了video.schedule目的

video.schedule字段
欄位 類型 描述
ends_at 以 ISO-8601 日期格式表示的字串 影片無法觀看的日期-時間
starts_at 以 ISO-8601 日期格式表示的字串 影片可供觀賞的日期與時間

Video Cloud攝取字段

Video Cloud攝取字段
欄位 類型 描述
audio_tracks僅限選擇性動態傳送 物件 []

音軌對像數組-請參閱使用API實施多個音軌欲獲得更多信息。

audio_tracks.merge_with_existing選擇性 布林值

是否替換現有的音軌或添加新的音軌(僅當前)false支持)僅動態投放

默認值:false

audio_tracks.masters選擇性 物件 []

音訊軌物件陣列僅動態傳遞

audio_tracks.masters.url選擇性 字串

音頻文件的URL 僅動態投放

audio_tracks.masters.language選擇性 字串

來自中的子標籤的音軌的語言代碼https://www.iana.org/assignments/language-subtag-registry/language-subtag-registry(可以通過聯繫Brightcove支持為帳戶設置默認值)僅動態投放

audio_tracks.masters.variant選擇性 字串

音軌的類型(可以通過聯繫Brightcove支持為帳戶設置默認值)僅動態投放

允許值:"main" , "alternate" , "commentary" , "dub" , "descriptive"

profile選擇性 字串

用於轉碼的攝取配置文件的 ID (不是名稱);如果不存在,將使用默認配置文件(省略此字段並建議使用默認配置文件)

text_tracks選擇性 物件 []

的數組text_tracks對象-請參閱攝取WebVTT文件(文本軌道)

text_tracks.url 網址

WebVTT文件的URL

text_tracks.srclang 字串

文本軌道的ISO 639 2字母(alpha-2)語言代碼

text_tracks.kind選擇性 字串

如何使用vtt文件

默認值:captions

允許的值:"captions""subtitles""chapters""metadata"

text_tracks.label選擇性 字串

用戶可讀的標題

text_tracks.default選擇性 布林值

設置字幕/字幕的默認語言

capture-images選擇性 布林值

在轉碼過程中是否應捕獲海報和縮略圖;默認為true如果個人資料具有圖像副本,false如果沒有,請參閱圖片和Dynamic Ingest API欲獲得更多信息

poster選擇性 物件

要攝取的視頻海報-請參閱圖片和Dynamic Ingest API欲獲得更多信息

poster.url 網址

視頻海報圖像的URL

poster.height選擇性 整數

圖像的像素高度

poster.width選擇性 整數

圖像的像素寬度

thumbnail選擇性 物件

要提取的視頻縮略圖-請參見圖片和Dynamic Ingest API欲獲得更多信息

thumbnail.url 網址

視頻縮略圖的網址

thumbnail.height選擇性 整數

圖像的像素高度

thumbnail.width選擇性 整數

圖像的像素寬度

callbacks選擇性 串[] URL數組通知應該發送到

 

API 回應

對創建剪輯請求的響應包括作業的ID和您在請求正文中設置的標籤,以及實時作業ID:

{
  "vod_jobs": [
    {
      "jvod_id": "9582606c50d84be5ad4bc104f2aa3360",
      "label": "last 60 secs of live job"
    }
  ],
  "live_job_id": "88ba5d87b61a4ef3a6dddabd0c38d319"
}

回應欄位

響應體字段
欄位 類型 描述
vod_jobs 物件

剪輯響應對象

jvod_id 字串

剪輯作業ID

label 字串

剪輯標籤(來自輸入)

live_job_id 字串

實時作業ID(來自輸入)