Live Ingest & Forwarding

ソースビデオを当社ネットワークへ直接「プッシュ」できない場合、Live Ingest & Forwarding 機能により任意の外部ソースからインジェストし、1つ以上の宛先へ再配信できます。強力なストリームリレーとして機能し、直接配信が不可能なワークフローでもAPIドリブンなソリューションを提供します。

プロセスは主に2つのアクションで構成されています：

• インジェスト（プル）: お客様が提供するソースURLから当社サービスがライブ映像フィードを「プル」で積極的にインジェストします。
• フォワード（プッシュ）: インジェストしたストリームを、お客様が指定した1つ以上のRTMP送信先URLへ再プッシュし、他のプラットフォームやCDNへのコンテンツシンジケーションを実現します。

この柔軟性により、いくつかの強力な用途が可能になります：

• ライブストリームシンジケーション（リストリーミング）: 単一のライブフィードをインジェストし、複数のプラットフォームに同時に配信します。複数のエンコーダーは不要であり、複数のソーシャルメディアやパートナープラットフォームで一度にオーディエンスへリーチしたい場合に最適です。

• VODからライブ放送へ: 動画ファイル（MP4、FLV）のプレイリストを連続再生の24時間ライブチャンネルに変換します。事前収録イベントの配信、リニアTV形式のチャンネル作成、ライブ予定の空き時間を埋める用途に最適です。

• サードパーティおよびレガシー入力: 外部エンコーダや、当社プラットフォームに直接プッシュできないソースとシームレスに統合できます。

• オンザフライ処理: 配信ストリームを最終配信先に再配信する前に、ウォーターマークの追加や基本的なトランスコーディングを実行できます。

• スケジュールオートメーション: APIを利用し、ライブイベントの開始・終了時間を自動化することで、手動操作なしにスケジュール通りの配信運用が可能です。

認証

すべてのAPIリクエストは、エンドポイントURLの末尾に付加される3つのクエリパラメータn、r、kによって認証されます。

• n: お客様のCDNetworksプラットフォームアカウント名。
• r: 一意のランダム文字列（最大32文字）。Unixタイムスタンプの利用を推奨します。
• k: 32文字のMD5署名。

MD5署名の計算方法

署名kはmd5(r + key)で計算されます。ここでkeyはお客様のシークレットAPIキーです。

1. シークレットキーの取得：CDNetworksカスタマーサービスへ連絡し、シークレットkeyを取得してください。
2. ランダム文字列の生成：r用にユニークな文字列を作成します。例：r = 1409284800。
3. 連結：ランダム文字列の末尾にシークレットキーを追加します。
   • 例えば、key = 012f37a3f2952の場合、結合後の文字列は1409284800012f37a3f2952となります。
4. MD5ハッシュの計算：結合した文字列からMD5ハッシュ値を計算し、kを取得します。
   • k = md5("1409284800012f37a3f2952")の計算結果はb9fed80be752551834eec3e52fa94115となります。

タスク管理

この機能は2つの方法で制御できます：

• リアルタイムタスク: アクティブなlive streamに対して即座に中継を開始または停止します。
• スケジュールタスク: まだライブ配信されていないstreamに対して、特定の開始および終了時刻をあらかじめ設定したタスク。

以下のエンドポイントは、live stream forwardingのタスク作成、停止、更新、再開に使用されます。

• HTTPメソッド: POST
• エンドポイント: http://livect.cdnetworks.com/api/cdn/v2/forwardRequest.action
• ヘッダー: Content-Type: application/json

リクエストURLの例：

http://livect.cdnetworks.com/api/cdn/v2/forwardRequest.action?n=your_account&r=1409284800&k=b9fed80be752551834eec3e52fa94115

リクエストボディの例（cmd=1、タスク作成）：

{
    "transcallbackurl": "http://example.com/api/callback",
    "cmd": "1",
    "type": "live",
    "list": [
        {
            "id": "task_unique_id_001",
            "src": [
                {
                    "url": "http://source.example.com/live/stream1.flv",
                    "wmImage": "http://source.example.com/assets/logo.jpg",
                    "wmGravity": "TOP_LEFT"
                },
                {
                    "url": "http://backup.example.com/live/stream1.flv"
                }
            ],
            "forward": [
                {
"url": "rtmp://[dest1.example.com/live/output](https://dest1.example.com/live/output)"
},
{
"url": "rtmp://[dest2.example.com/live/output](https://dest2.example.com/live/output)"
}
],
"start": "1495177025000",
"end": "1495184225000",
"fops": {
"bps": "1200000",
                "res": "1280x720",
                "fps": "25"
                "vcodec": "libx264",
                "forced_gopInterval": "3000"
            },
            "extendParam": {
                "waitCrtUrlFinish": "1"
            }
        }
    ]
}

本文パラメーター

項目	型	必須	説明
transcallbackurl	String	いいえ	ステータスおよびイベント通知（コールバック）が送信されるURLです。
cmd	String	はい	実行するコマンド： 1: タスクの作成および開始 2: タスクの停止 3: 実行中のタスクのsrcリストを更新 5: 停止中のタスクを再開
type	文字列	はい	コンテンツのタイプ。live はライブ配信、video はオンデマンドファイル（VOD）に使用します。
list	配列	はい	タスクオブジェクトの配列。詳細は下記をご参照ください。

list オブジェクトのパラメータ

フィールド	型	必須	説明
id	文字列	はい	タスクの一意な識別子（最大32文字）。既存の id で新しいタスクを送信すると、古いタスクが停止します。
src	配列	はい	ソースストリームオブジェクトの配列。詳細は下記をご参照ください。
forward	配列	はい	ストリームを転送する宛先オブジェクトの配列。詳細は下記をご参照ください。
start	String	任意	スケジュールされた開始時刻（ミリ秒単位の13桁のUnixタイムスタンプ）。未指定の場合はタスクが即時開始されます。
end	String	任意	スケジュールされた終了時刻（ミリ秒単位の13桁のUnixタイムスタンプ）。この時刻でタスクは自動的に停止します。
fops	Object	任意	トランスコードおよびエンコーディング設定。詳細は下記を参照してください。
extendParam	Object	任意	タスク動作の微調整のための高度なパラメーターです。詳細は下記を参照してください。

src オブジェクトのパラメーター

フィールド	型	必須	説明
url	String	必須	配信元からストリームを取得するためのソースURLです。冗長化のために複数のURLを指定できます。対応フォーマット： ライブプロトコル：RTMP、HLS (.m3u8)、HTTP-FLV、RTSP ビデオフォーマット：MP4、FLV、HLS (.m3u8)
wmImage	String	いいえ	ウォーターマーク画像のURL。複数のウォーターマークを指定する場合はセミコロン（;）区切りで指定してください。 注意: URL内に & など特別な文字が含まれる場合は、URLエンコードする必要があります。
wmGravity	String	いいえ	ウォーターマークの静的な表示位置。デフォルトはTOP_RIGHTです。利用可能なオプション：TOP_LEFT、TOP_CENTER、TOP_RIGHT、CENTER_LEFT、CENTER、CENTER_RIGHT、BOTTOM_LEFT、BOTTOM_CENTER、BOTTOM_RIGHT。
wmPosition	String	いいえ	動画サイズに対し、ウォーターマークの左上の位置をパーセンテージで指定します。フォーマットはWxH%（Wは左端からのパーセンテージ、Hは上端からのパーセンテージ）です。 例：30%x40%の場合、動画の幅の30％、高さの40％の位置からウォーターマークを配置します。値は0～99までの整数である必要があります。 このパラメータはwmGravityと排他関係です。両方指定した場合、想定外の挙動になる可能性があります。
relofftime	String	いいえ	タスクの相対的な時間セグメント（秒単位）を指定します。 動作はストリームのtypeによって異なります： VOD（type=video）の場合：フォーマットは[start_second]-[end_second]です。ソースファイルのうち指定した区間のみを配信します。例：30-60と設定すると、動画の30秒地点から60秒地点までの部分のみが使用されます。 ライブ（type=live）の場合：フォーマットは0-[duration_in_seconds]です。ライブストリームをプル＆フォワードする合計時間を示します。例：0-60の場合、ライブ配信を60秒中継します。
pullStreamHeaders	Array	いいえ	ソースストリームをプルする際にリクエストへ付与するカスタムHTTPヘッダーオブジェクトの配列です。 注意： 1. 合計長は2KBを超えてはいけません。 値にはシングルクォート（'）、ダブルクォート（"）、連続するセミコロン（;;）、カンマ（,）、改行文字を含められません。 例：[{"headerKey": "User-Agent", "headerValue": "MyCustomPlayer/1.0"}, {"headerKey": "Referer", "headerValue": "http://example.com"}]

forward オブジェクトパラメータ

フィールド	型	必須	説明
url	String	必須	転送先のRTMP URLです。複数のURLを指定可能ですが、システムは各転送先を個別の転送タスクとして扱います。
resetUrl	String	任意	cmd=5でタスクを再開する際に使用する新しい転送先URL。

注意: 転送の宛先にはRTMPプロトコルのみサポートしています。

fops オブジェクトパラメーター（トランスコード）

Field	Type	必須	説明
bps	String	任意	目標ビデオビットレート（例：1.2 Mbpsの場合は1200000）。
res	String	任意	目標解像度（例：1280x720）。xは小文字で記載してください。
fps	String	いいえ	対象のフレーム毎秒（例：25）。
vcodec	String	いいえ	出力映像コーデック（例：libx264、libx265）。省略した場合、出力はソース映像のコーデックを保持します。ウォーターマークを使用する場合、vcodecはlibx264に設定する必要があります。
acodec	String	いいえ	出力音声コーデック（例：libmp3lame、libfaac、libvorbis）。省略した場合、出力はソース音声のコーデックを保持します。
bufferTime	String	いいえ	HLSソースの場合、ソースの不安定を吸収するためのバッファ秒数。デフォルトは0です。レイテンシが増加します。
forced_gopInterval	String	いいえ	希望するキーフレーム間隔（ミリ秒）（例：3秒のGOPは3000）。

extendParam オブジェクトのパラメーター

項目	型	必須	説明
waitCrtUrlFinish	String	いいえ	VODファイルのsrcリストをcmd=3で更新する場合、1は現在のファイルの再生終了まで待機してから切り替えます。0（デフォルト）は即座に切り替わります。
loop	String	いいえ	VODファイルのループ動作を制御します。デフォルトは1（一度再生）です。無限ループの場合は-1を使用してください。 注意: loopとタスクのend時刻が両方設定されている場合は、end時刻が優先されます。
index	String	いいえ	VODタスク（type=videoの場合）のみ有効。srcリスト内の再生開始ファイルを位置（index）で指定します。デフォルトは1で、最初のファイルから開始します。

パラメータ優先順位に関する注意:
タスクでend（listオブジェクト内）、loop（extendParam内）、relofftime（srcオブジェクト内）が全て指定された場合、優先順位は以下の通りです：end > loop > relofftime。満たされた最も優先度の高いパラメータに基づきタスクは停止します。

APIレスポンス

APIは、標準HTTPステータスコードとビジネスレベルのステータスを含むJSONボディを返します。

サンプル成功応答：

{
    "http_code": "200",
    "msg": "タスクの受信に成功しました！"
    "call_time": 1479952114000
}

一般的なHTTPステータスコード：

• 200 OK: リクエストが受け付けられました。ビジネスレベルの結果についてはJSON本体をご確認ください。
• 400 Bad Request: リクエスト形式が正しくありません（例：無効なJSONや必須項目の欠如など）。
• 403 Forbidden: 認証に失敗しました（例：不正なk署名、無効なr値、リクエスト制限超過など）。
• 5xx Server Error: サーバーで予期しないエラーが発生しました。

JSON本体内のビジネスレベル http_code：

HTTP	http_code	msg 例	説明	推奨アクション
200	200	receive task success!	タスクの受信および処理待ちキューへの登録が成功しました。	なし。
400	1001	cmd is error	cmd フィールドが正しくありません。	cmd は 1、2、3、5 のみサポートされています。
400	1001	type is error	type フィールドが正しくありません。	type は live または video のみサポートされています。
400	1001	list is null	list 配列が存在しないか、空です。	このフィールドは必須です。
400	1001	params id is null	list オブジェクト内の id フィールドが存在しないか、空です。	このフィールドは必須です。
400	1001	params src list is null	src 配列が存在しないか、空です。	このフィールドは必須です。
400	1001	params src num is too long	src 配列内の項目数が上限を超えています。	最大800件までです。元の数を減らしてください。
400	1001	params src length is too long	src配列内の内容の合計文字数が上限を超えています。	最大は204,800文字です。内容のサイズを減らしてください（例：URLを短くするなど）。
400	1001	params src is error	srcオブジェクト内のurlが存在しないか、空になっています。	この項目は必須です。
400	1001	params relofftime is error	relofftimeのフォーマットが不正です。	正しい書式についてはパラメータ説明を参照してください。
400	1001	params forward list is null	forward配列が存在しないか、空になっています。	この項目は必須です。
400	1001	params forward is error	forwardオブジェクト内のurlが存在しないか、空になっています。	この項目は必須です。
400	1001	params start format is error	startの時刻フォーマットが不正です。	13桁のUnixタイムスタンプ（ミリ秒）でなければなりません。
400	1001	params end format is error	endの時刻フォーマットが不正です。	13桁のUnixタイムスタンプ（ミリ秒）でなければなりません。
400	1001	params end plan is error!	end時刻が過去になっています。	終了時刻は現在時刻以降でなければなりません。
400	1001	params start and end interval Too Brief!	startからendまでの間隔が短すぎます。	最小間隔は5分です。
400	1001	params ${field} format is error	指定されたフィールドのフォーマットが不正です。	正しい書式についてはAPIドキュメントを参照してください。
403	1002	apiName, n, r, k not exist or empty	いずれかの認証パラメータが不足しています。	リクエストURLに n、r、k をすべて含めてください。
403	1002	random.length gt 32 or key.length ne 32	r または k のパラメータ長が不正です。	r は32文字以内、k は正確に32文字である必要があります。
403	1002	you do not have right to access this api	このAPIを利用する権限がありません。	アカウントでAPIアクセスが有効になっているかご確認ください。有効化には5～10分かかる場合があります。
403	1002	k is error	k パラメータ（MD5署名）が正しくありません。	MD5計算方法とシークレットキーをご確認ください。
403	1002	frequency is great than limitCount	APIコールのレート制限を超えています。	コール頻度を下げてください。リミットは通常5分ごとにリフレッシュされます（例：5分間で100回）。
403	1002	random is repeat	r の値が短時間に重複して使用されています。	各リクエストごとに r を一意に設定してください。タイムスタンプの利用を推奨します。
403	1002	user and host not relation	指定したdomainに対するアカウント権限がありません。	サブアカウントの場合、コントロールパネルのdomainリストでdomainが設定されているかご確認ください。

タスク照会

このエンドポイントでは、タスクのステータスおよび詳細情報を取得できます。

• HTTPメソッド: GET
• エンドポイント: http://livect.cdnetworks.com/api/cdn/v2/forwardQueryByPage.action

リクエストURLの例:

http://livect.cdnetworks.com/api/cdn/v2/forwardQueryByPage.action?n=test&r=1741165183&k=a6edsa3c30d64e172b52136ba493ad1f&id=task_unique_id_001

クエリパラメータ

フィールド	必須	説明
n, r, k	必須	標準認証パラメータ。
id	条件付き	一意のタスクid（完全一致）。
src	条件付き	ソースURL（あいまい一致）。
forward	条件付き	転送先URL（あいまい一致）。
pageNo	いいえ	ページネーションされた結果のページ番号。デフォルトは1です。
pageSize	いいえ	1ページあたりの結果数。デフォルトは100、最大値も100です。

注意：id、src、またはforwardのうち少なくとも1つを指定する必要があります。

クエリレスポンス本文

サンプルクエリレスポンス：

{
    "total": 1,
    "pageNo": 1,
    "pageSize": 100,
    "list": [
        {
            "id": "task_unique_id_001",
            "type": "cloud live streaming",
            "src": "[{\"url\":\"http://source.example.com/live/stream1.flv\"}]",
            "forward": "rtmp://[dest1.example.com/live/output](https://dest1.example.com/live/output)",
            "cmd": "1",
            "code": "0",
            "msg": "Start stream pushing!",
            "startTime": "2025-03-05 16:05:12",
            "endTime": ""
        }
    ]
}

コールバック

タスク作成リクエストに transcallbackurl が指定されている場合、システムはタスクのステータス変更を通知するために、そのURLへJSONペイロード付きの POST リクエストを送信します。

コールバックボディのサンプル:

{
    "id": "task_unique_id_001",
    "srcurl": "[{\"url\":\"http://source.example.com/live/stream1.flv\"}]",
    "forwardurl": "rtmp://[dest1.example.com/live/output](https://dest1.example.com/live/output)",
    "cmd": "1",
    "code": "0",
    "msg": "プッシュを開始します！",
    "event_time": 1600402486054
}

コールバックcodeおよびmsgリファレンス

code	msg 説明	意味
0	Start pushing!	ストリームフォワーディングが正常に開始されました。
1	Push stream success	タスクは正常に完了しました（例：VODファイルが終了した、スケジュールされた終了時間に達したなど）。
2	live_pull failed:xxxxx	外部エラーによりフォワーディングが停止しました（例：ソースストリームが利用できなくなった、接続が切断されたなど）。
3	Push stream failed!	サーバ内部エラーによりフォワーディングが停止されました。
4	(file): Server returned 404...	クリティカルではない警告が発生しました（例：プレイリスト内のVODファイルが見つかりませんでした）。タスクは次の項目で続行を試みます。
5	list update success	情報更新です。主にVODカルーセルで新しいファイルが処理中であることを示します。
90	task not exists	指定されたタスクIDが見つかりませんでした（cmd値が2、3、5の場合に適用されます）。
91	task repeat,task not start!	同じ宛先URLのタスクがすでに実行中です。
92	task start delivery failed!	システムがタスクの開始に失敗しました。再試行してください。

重要な注意事項

1. タスクの存続期間:

   • リアルタイム：startとendが省略された場合、タスクはcmd=2が呼び出されるか、ソースストリームが切断されるまで実行されます。
   • スケジュール実行：start および end が指定されている場合、タスクはその期間内に実行されます。なお、cmd=2 で早期停止も可能です。

2. 時間制限：

   • 指定した start と end の間の期間は、最低5分以上である必要があります。
   • end 時刻は必ず未来である必要があります。

3. トランスコーディング：fops でトランスコーディングパラメータ（bps、res、fpsなど）を設定する場合は、必ず vcodec も指定してください。

4. タスクの更新（cmd=3）：このコマンドは、既に実行中のタスクのソース（src）を更新するために使用します。アップデートリクエストで fops や extendParam も含めることが可能です。ただし、スケジュールタスクがまだ開始されていない場合は、まず cmd=2 でキャンセルし、新しい設定で再作成してください。

5. タスクの再開（cmd=5）：このコマンドは停止したタスクを再開します。タスク停止から48時間以内に利用できます。停止には2種類があり、それぞれ異なる再開動作となります：

   • 自然停止：src リスト内の全ファイルの再生が終了した場合に発生します。cmd=5 で再開すると、リスト内最初のファイルから再スタートします。

   • 手動停止：cmd=2 コマンドでタスクが手動で停止された場合です。cmd=5 で再開すると、中断ポイントから続行されます。

     再開リクエストでは、fopsおよびextendParamは無視され、id・src・forwardパラメータが元のタスクと一致していれば十分です。必要に応じて、resetUrlで新しい送信先を指定できます。

6. タスクの停止（cmd=2）について：

   • このコマンドは、指定されたタスクのForward Pushを停止します。idは稼働中のタスクと一致している必要があります。
   • 複数のForward Push先があるタスクで特定の転送先のみ停止したい場合は、停止リクエストの forward 配列に、その転送先のURLのみを含めてください。
   • タスク全体を停止する場合、cmd=2 リクエストの forward リストには、そのタスクで現在有効なすべてのForward Push URL、もしくはタスク作成時または最新の更新時に指定した完全な forward リストを含めることが推奨されます。
   • 停止リクエストの forward 配列のURLは、タスク作成（cmd=1）時または最新の変更（cmd=3）時に使用したURLと完全に一致している必要があります。
   • すべての関連するForward Pushストリームが正常に停止されて初めて、タスクは完全に終了したと見なされます。

7. Rate Limiting：APIコールの頻度制限（通常は5分間に100回）にご注意ください。この制限を超えると、403 Forbidden エラーが発生します。

8. パラメータ形式について：APIリクエストではsrcおよびforwardはJSON配列ですが、コールバックメッセージではsrcurlおよびforwardurlフィールドにstringified JSONとして渡されます。