뒤로
Media Acceleration Live Broadcast
다큐멘트 센터 Media Acceleration Live Broadcast Product Features Live Ingest & Forwarding

Live Ingest & Forwarding

최신 업데이트：2025-10-20 17:13:13

소스 비디오를 당사 네트워크로 직접 "푸시"할 수 없는 경우, Live Ingest & Forwarding 기능을 통해 외부 소스에서 인제스트하여 하나 또는 그 이상의 목적지로 재분배할 수 있습니다. Stream relay로서 동작하며, 직접 게시가 불가능한 워크플로우에 대해 API 기반 솔루션을 제공합니다.

이 프로세스는 두 가지 주요 작업으로 구성됩니다:

  • Ingest (Pull): 당사 서비스는 귀하가 제공한 소스 URL에서 “풀” 방식으로 라이브 비디오 피드를 적극적으로 인제스트합니다.
  • Forward (Push): 인제스트된 스트림은 사용자가 정의한 하나 이상의 RTMP 대상 URL로 다시 푸시되어, 다른 플랫폼이나 CDN으로 콘텐츠 연동이 가능합니다.

이러한 유연성은 여러 강력한 활용 사례를 실현합니다:

  • Live Stream Syndication (Restreaming): 단일 라이브 피드를 인제스트한 후, 여러 플랫폼에 동시에 방송하여 여러 인코더 없이 다양한 소셜 미디어 사이트 및 파트너 플랫폼의 시청자에게 동시에 도달할 수 있습니다.

  • VOD에서 라이브 방송 전환: 재생 목록의 비디오 파일(MP4, FLV 등)을 연속적이고 24/7 라이브 채널로 변환합니다. 사전 녹화된 이벤트 방송, 선형 TV 스타일 채널 생성 또는 라이브 스케줄의 공백 시간 채워넣기에 이상적입니다.

  • 서드파티 및 레거시 인제스트: 외부 인코더나 우리 플랫폼에 직접 푸시할 수 없는 소스와 원활하게 통합할 수 있습니다.

  • 온더플라이 처리: 최종 목적지로 재분배되기 전에 스트림에 워터마크 적용 혹은 기본 트랜스코딩을 실시간으로 수행할 수 있습니다.

  • 예약 자동화: API를 사용하여 라이브 이벤트의 시작 및 종료 시간을 자동화하여 수동 개입 없이 방송이 정해진 일정에 맞춰 진행되도록 합니다.

인증

모든 API 요청은 엔드포인트 URL에 추가되는 세 가지 쿼리 파라미터 n, r, k를 사용해 인증해야 합니다.

  • n: 귀하의 CDNetworks 플랫폼 계정명입니다.
  • r: 고유한 랜덤 문자열(최대 32자)입니다. Unix 타임스탬프도 좋은 선택입니다.
  • k: 32자리 MD5 서명입니다.

MD5 서명 계산

서명 k는 md5(r + key)로 계산되며, 여기서 key는 귀하의 비밀 API key입니다.

  1. Secret Key 획득: Secret key를 받기 위해 CDNetworks 고객센터에 문의하세요.
  2. 랜덤 문자열 생성: r 값으로 사용할 고유 문자열을 만드세요. 예시: r = 1409284800.
  3. 문자열 연결: 랜덤 문자열 뒤에 Secret Key를 붙이세요.
    • 만약 key = 012f37a3f2952라면, 합쳐진 문자열은 1409284800012f37a3f2952가 됩니다.
  4. MD5 해시 계산: 결합된 문자열의 MD5 해시를 계산해 k 값을 구하세요.
    • k = md5("1409284800012f37a3f2952") 결과는 b9fed80be752551834eec3e52fa94115입니다.

작업 관리

이 기능은 두 가지 방법으로 제어할 수 있습니다:

  • 실시간 작업: 활성화된 실시간 스트림에 대해 즉시 릴레이를 시작하거나 중지합니다.
  • 예약 작업: 아직 Live 상태가 아닌 스트림에 대해 특정 시작 및 종료 시간을 사전 구성하여 작업을 예약합니다.

다음 엔드포인트를 사용하여 라이브 스트림 포워딩 작업을 생성, 중지, 업데이트 및 재개할 수 있습니다.

  • 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"
            }
        }
    ]
}

Body Parameters

Field Type Required Description
transcallbackurl String 아니오 상태 및 이벤트 알림(콜백)이 전송될 URL.
cmd String 예 실행할 명령어:
1: 태스크 생성 및 시작.
2: 태스크 중지.
3: 실행 중인 태스크의 src 목록 업데이트.
5: 중지된 태스크 재개.
type String Yes 콘텐츠 유형입니다. 라이브 스트림의 경우 live, 주문형 파일(VOD)의 경우 video를 사용하세요.
list Array Yes 작업 객체의 배열입니다. 아래에서 자세한 내용을 확인하세요.

list 객체 파라미터

Field Type Required Description
id String Yes 작업의 고유 식별자(최대 32자). 기존 id로 새로운 작업을 제출하면 이전 작업이 중지됩니다.
src Array Yes 소스 스트림 객체의 배열입니다. 아래에서 자세한 내용을 확인하세요.
forward Array Yes 스트림이 전달될 대상 객체의 배열입니다. 아래에서 자세한 내용을 확인하세요.
start String 아니오 예약된 시작 시간(13자리 Unix 타임스탬프, ms 단위)입니다. 생략 시 작업이 즉시 시작됩니다.
end String 아니오 예약된 종료 시간(13자리 Unix 타임스탬프, ms 단위)입니다. 해당 시간에 작업이 자동으로 종료됩니다.
fops Object 아니오 트랜스코딩 및 인코딩 설정입니다. 아래에서 자세한 내용을 확인하세요.
extendParam Object 아니오 작업 동작을 세밀하게 조정하기 위한 고급 파라미터입니다. 자세한 내용은 아래를 확인하세요.

src 오브젝트 파라미터

필드 타입 필수 여부 설명
url String 예 스트림을 가져올 소스 URL입니다. 여러 개의 URL을 중복(이중화) 구성으로 제공할 수 있습니다.
라이브 프로토콜: RTMP, HLS(.m3u8), HTTP-FLV, RTSP
비디오 포맷: MP4, FLV, HLS(.m3u8)
wmImage String 아니오 워터마크 이미지의 URL입니다. 여러 개의 워터마크가 있을 경우, 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 오브젝트 파라미터(트랜스코딩)

필드 타입 필수 여부 설명
bps String 아니오 비디오 목표 비트레이트(단위: bps, 예: 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 목록에서 파일의 위치(인덱스)로 시작 파일을 지정합니다. 기본값은 1로, 첫 번째 파일부터 시작합니다.

파라미터 우선순위 안내:
작업에 대해 end(리스트 오브젝트 내), 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 작업 수신 성공! 작업이 성공적으로 수신되어 처리 대기열에 등록되었습니다. 해당 없음.
400 1001 cmd가 잘못되었습니다 cmd 필드가 올바르지 않습니다. cmd는 1, 2, 3, 5만 지원합니다.
400 1001 type이 잘못되었습니다 type 필드가 올바르지 않습니다. type은 live 또는 video만 지원합니다.
400 1001 list가 비어 있습니다 list 배열이 누락되었거나 비어 있습니다. 필수 입력 항목입니다.
400 1001 params id가 비어 있습니다 list 객체 내의 id 필드가 누락되었거나 비어 있습니다. 필수 입력 항목입니다.
400 1001 params src list가 비어 있습니다 src 배열이 누락되었거나 비어 있습니다. 필수 입력 항목입니다.
400 1001 params src num이 너무 많습니다 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 timestamp이어야 합니다.
400 1001 params end format is error end 시간 형식이 올바르지 않습니다. 13자리 밀리초 단위의 Unix timestamp이어야 합니다.
400 1001 params end plan is error! end 시간이 과거로 설정되어 있습니다. 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이 구성되어 있는지 확인하세요.

Task Query

이 엔드포인트는 작업의 상태와 세부 정보를 조회할 수 있습니다.

  • 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 조건부 고유 Task id (정확히 일치).
src 조건부 소스 URL(모호 일치).
forward 조건부 포워딩 대상 URL(모호 일치).
pageNo 아니오 페이지 결과의 페이지 번호. 기본값은 1입니다.
pageSize 아니오 페이지당 결과 수. 기본값은 100이며, 최대값도 100입니다.

참고: id, src, forward 중 적어도 하나는 반드시 입력해야 합니다.

쿼리 응답 본문

샘플 쿼리 응답:

{
    "total": 1,
    "pageNo": 1,
    "pageSize": 100,
    "list": [
        {
            "id": "task_unique_id_001"
            "type": "live",
            "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": "Stream pushing started!",
            "startTime": "2025-03-05 16:05:12",
            "endTime": ""
        }
    ]
}

콜백

task 생성 요청 시 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 참조

코드 메시지 설명 의미
0 푸시 시작! 스트림 포워딩이 성공적으로 시작되었습니다.
1 푸시 스트림 성공 작업이 정상적으로 완료되었습니다(예: VOD 파일 전송 종료, 예약된 종료 시간 도달).
2 live_pull 실패:xxxxx 외부 오류로 인해 포워딩이 중단되었습니다(예: 소스 스트림이 사용할 수 없거나 연결이 끊어짐).
3 푸시 스트림 실패! 내부 서버 오류로 인해 스트림 포워딩이 중단되었습니다.
4 (파일): 서버에서 404 반환... 중요하지 않은 경고가 발생했습니다(예: 재생목록의 VOD 파일을 찾을 수 없음). 작업이 다음 항목으로 이어집니다.
5 리스트 업데이트 성공 새로운 파일이 처리 중임을 나타내기 위해 VOD 캐러셀에서 자주 사용되는 정보성 업데이트입니다.
90 task not exists 요청하신 작업 ID를 찾을 수 없습니다(cmd 값이 2, 3, 5인 경우에 적용됩니다).
91 task repeat,task not start! 동일한 대상 URL을 가진 작업이 이미 활성화되어 있습니다.
92 task start delivery failed! 시스템에서 작업을 시작하지 못했습니다. 다시 시도해 주시기 바랍니다.

중요 참고 사항

  1. 작업 수명(Lifetime):

    • 실시간: 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시간 이내에 사용할 수 있습니다. 작업 중지 유형에 따라 재개 방식이 다릅니다:

    • 자연 중지: src 목록의 모든 파일 재생이 완료되면 발생합니다. cmd=5로 재개하면 목록의 첫 번째 파일부터 작업이 다시 시작됩니다.

    • 수동 중지: cmd=2 명령으로 작업이 중지된 경우 발생합니다. cmd=5로 재개하면 중단된 지점부터 계속 진행됩니다.

      resume 요청은 fops 및 extendParam을 무시하며, 원래 작업과 동일한 id, src 및 forward 파라미터만 필요합니다. 필요시 resetUrl로 새로운 대상지를 지정할 수 있습니다.

  6. 작업 중단(cmd=2):

    • 이 명령은 지정된 작업의 전송을 중지합니다. id 값은 실행 중인 작업과 일치해야 합니다.
    • 여러 대상지로 전송하는 작업의 경우, 특정 대상지에 대한 전송만 중단하려면 중지 요청의 forward 배열에 해당 대상지의 URL만 포함시키면 됩니다.
    • 전체 작업을 중지하려면, cmd=2 요청의 forward 목록에 해당 작업의 모든 활성 전송 URL을 포함하거나, 작업이 최초 생성되었거나 마지막으로 갱신될 때 제공된 전체 forward 목록과 일치시키는 것이 이상적입니다.
    • 중지 요청의 forward 배열 내 URL은 작업이 생성(cmd=1)되었거나 마지막으로 수정(cmd=3)되었을 때 사용된 URL과 정확히 일치해야 합니다.
    • 모든 관련 전송 스트림이 성공적으로 중지되어야만 작업이 완전히 종료된 것으로 간주됩니다.

  7. Rate Limiting: API 호출 빈도 제한(일반적으로 5분에 100회)에 유의하세요. 이 제한을 초과할 경우 403 Forbidden 오류가 발생합니다.

  8. 파라미터 형식: API 요청에서 src와 forward는 JSON 배열이지만, 콜백 메시지의 srcurl 및 forwardurl 필드에서는 문자열 형태의 JSON으로 전달된다는 점에 유의하십시오.

이 문서의 내용이 도움이 되었습니까?
예
아니오
정상적으로 제출되었습니다.피드백을 주셔서 감사합니다.앞으로도 개선을 위해 노력하겠습니다.

CDNetworks Inc., © 2025. 1840 Enterprise Way, Monrovia, CA 91016 – All rights reserved.