Skip to content

Live Station API

Jump to bottom
Hamp edited this page Nov 8, 2024 · 13 revisions

네이버 클라우드의 Live Station API를 정리한 문서입니다.

Live Station Flow

Live Station Flow

1. 디바이스에서 영상 준비

디바이스에서 실시간 영상 및 오디오 데이터를 수집합니다.

2. RTMP 프로토콜에 맞게 인코딩

영상 데이터를 RTMP 스트리밍에 맞게 인코딩합니다. H.264또는 H.265와 같은 코덱을 사용합니다.

3. RTMP 프로토콜을 통한 전송

인코딩된 데이터를 RTMP 프로토콜을 통해 Live Station 채널로 송출합니다. 이 단계에서 데이터가 CDN을 통해 스트리밍됩니다.

4. Transcoding 절차

Live Station 에서 Transcoding 절차를 통해 원본 영상 데이터를 변환 및 최적화하여 .m3u8 확장자로 변환합니다.

5. HLS 송출 및 전송

.m3u8 파일이 생성되면 HLS(HTTP Live Streaming) 방식으로 각 디바이스에 실시간 스트리밍 송출을 진행합니다.

6. 디바이스 재생

각 디바이스에서 HLS 스트림을 수신하고 재생하여 사용자는 실시간으로 영상을 시청할 수 있습니다.

Live Station API (링크)

시나리오

  1. 공통 설정
  2. API Gateway 인증
  3. Global Edge 프로필 생성
  4. 채널 생성
  5. 채널 정보 조회
  6. 방송 수신
  7. 채널 정지
  8. 채널 삭제
  9. Global Edge(CDN) 정지
  10. Global Edge(CDN) 조회
  11. Global Edge(CDN) 삭제

0. 공통 설정 (링크)

Live Station API URL

https://livestation.apigw.ntruss.com/api/v2

Live Station API 요청 구성

  • Live Station API HTTP Request와 Response Body를 통해 전달되는 모든 데이터의 Content-type은 application/json을 사용합니다.
Header
  Content-Type:application/json
  x-ncp-apigw-timestamp:{Timestamp}
  x-ncp-iam-access-key:{Sub Account Access Key}
  x-ncp-apigw-signature-v2:{API Gateway Signature}
  x-ncp-region_code:KR
Body
  Json Object
URL
  https://livestation.apigw.ntruss.com/api/v2/{action}

요청 헤더

헤더명 필수여부 설명
x-ncp-apigw-timestamp YES 1970년 1월 1일 00:00:00 UTC부터의 경과 시간(밀리초 단위)
API Gateway 서버와의 시간 차가 5분 이상 나면 유효하지 않은 요청으로 간주
x-ncp-iam-access-key YES 네이버 클라우드 플랫폼 포털에서 발급받은 Access Key ID 값
x-ncp-apigw-signature-v2 YES Access Key ID 값과 Secret Key로 암호화한 서명 , HMAC 암호화 알고리즘은 HmacSHA256 사용
Content-Type YES Request body content type을 application/json으로 지정
x-ncp-region_code YES 리전 코드(KR)

요청 샘플

curl -i -s -X POST \
   -H "Content-Type:application/json" \
   -H "x-ncp-apigw-timestamp:1521787414578" \
   -H "x-ncp-iam-access-key:6uxz1nKkcYwUjWRG5Q1V7NsW0i5jErlu2NjBXXgy" \
   -H "x-ncp-apigw-signature-v2:iJFK773KH0WwQ79PasqJ+ZGixtpDQ/abS57WGQdld2M=" \
   -H "x-ncp-region_code:KR" \
   "https://livestation.apigw.ntruss.com/api/v2/channles"\
   -d "{ \"channelName\": \"api-guide\", \"qualitySetId\": 1234, \"qualitySetId\": false, \"record\" : {\"type\":\"NO_RECORD\"}, \"cdn\": { \"createCdn\" : true, \"cdnType\": \"GLOBAL_EDGE\", \"profileId\":1111, \"regionType\":\"KOREA\", \"cdnInstanceNo\":123456}, \"drmEnabledYn\":false}"

1. API Gateway Signature 생성 (링크)

  • 인증키 생성: 포털에서 생성 Access Key와 Secret Key생성
  • 시그니처 생성: Access Key와 Secret Key HmacSHA256 알고리즘으로 암호화한 후 Base64로 인코딩

2. Global Edge 프로필 생성 (링크)

요청 URL

POST https://edge.apigw.ntruss.com/api/v1/profile

요청 바디

항목 필수여부 타입 제약사항 설명
name Yes String 영어, 대시, 언더바 허용 최소 3자, 최대 35자 생성할 Profile 이름

요청 예시

POST /api/v1/profile
HOST: edge.apigw.ntruss.com
Content-Type: application/json
x-ncp-apigw-timestamp:1521787414578
x-ncp-iam-access-key:6uxz1nKkcYwUjWRG5Q1V7NsW0i5jErlu2NjBXXgy
x-ncp-apigw-signature-v2:iJFK773KH0WwQ79PasqJ+ZGixtpDQ/abS57WGQdld2M=

Request Body
{
  "name": "my-sample-profile"
}

3. 채널 생성 (링크)

요청 URL

POST https://livestation.apigw.ntruss.com/api/v2/channels

요청 바디

필수

필드명 필수여부 타입 제약사항 설명
channelName Yes String 최소 3글자 이상 최대 20자 문자까지 입력 가능
특수 문자 붙임표(_) 허용		 생성할 채널의 이름
cdn Yes Object CDN Object
cdn.createCdn Yes Boolean true, false CDN Object
cdn.cdnType Yes String GLOBAL_CDN, GLOBAL_EDGE CDN+ 미지원
cdn.profileId Yes Integer GLOBAL_EDGE 신규 생성 시 필요한 Global Edge의 프로필
cdn.regionType Yes String KOREA, JAPAN, GLOBAL Global Edge 서비스 지역
qualitySetId Yes Integer LL-HLS 채널을 생성할 경우, Low Latency 용 화질 세트 요청
useDvr Yes Boolean true, false DVR 사용 여부
record Yes Object 녹화 설정
record.type Yes String NO_RECORD, AUTO_UPLOAD, MANUAL_UPLOAD 저장된 녹화 파일 업로드 타입을 지정
"NO_RECORD"로 설정 시 녹화 기능 사용 불가
drmEnabledYn Yes Boolean DRM Encryption 설정 적용 유무
  • useDvr: useDvr는 DVR(Digital Video Recorder)기능의 사용 여부를 설정하는 옵션

Optional 이지만 필요해 보이는 필드

필드명 필수여부 타입 제약사항 설명
envType Optional String DEV, STAGE, REAL 입력하지 않을 경우 REAL로 디폴트 설정
immediateOnAir Optional Boolean true, false 송출과 동시에 녹화가 진행되는 자동 녹화 옵션
timemachineMin Optional Integer 단위는 분(minutes)이며 360으로만 설정 가능
useDvr이 true일 경우 반드시 설정해야 함		 녹화 시작 시점까지 영상을 되돌려 볼 수 있는 타임머신 기능 관련 옵션
  • envType: DEV(개발 환경), STAGE(서비스에 반영하기 전), REAL(실제 서비스)
  • immediateOnAir: false일 경우에는 방송이 자동으로 녹화되지 않으며, 수동으로 녹화를 시작

Optional

필드명 필수여부 타입 제약사항 설명
outputProtocol Optional String HLS, DASH, LL_HLS 입력하지 않을 경우 HLS로 디폴트 설정
cdn.cdnInstanceNo Optional Integer cdn.createCdn이 false일 경우 반드시 설정해야 함 기존 CDN 인스턴스 번호 설정
record.format Optional String MP4, HLS, ALL 버킷으로 자동 저장되는 녹화 파일의 타입을 지정
record.bucketName Optional String 자동 저장 기능을 통해 라이브 방송 종료 후 입력한 Bucket에 녹화 파일이 자동 저장
record.filePath Optional String "/"부터 시작해야 함 자동 저장 기능을 통해 라이브 방송 종료 후 지정한 filePath에 녹화 파일이 자동 저장
record.accessControl Optional String PRIVATE, PUBLIC_READ
Default: PRIVATE		 자동 저장 기능을 통해 녹화 파일 업로드 시 Object Storage Bucket 공개 범위를 지정하는 옵션
isStreamFailOver Optional Boolean true, false 송출 이중화 적용을 위한 옵션
송출 이중화 설정을 통해 송출 인코더 이중화 구성
drm Optional Object Live Station을 활용한 DRM Encryption 설정
DRM 설정 시 FairPlay, Widevine/PlayReady DRM 지원
drm.siteId Optional String One Click Multi DRM 상품을 통해 생성한 site id
drm.contentId Optional String 최소 3글자 이상 영문/숫자 또는 ‘-'(하이픈), ‘_'(언더바) 포함 최대 100자 문자까지 입력 가능 DRM Encryption을 적용할 콘텐츠의 고유 ID
DRM 패키징을 위해 사용

요청 예시

POST /api/v2/channels
HOST: livestation.apigw.ntruss.com
Content-Type: application/json
x-ncp-apigw-timestamp:1521787414578
x-ncp-iam-access-key:6uxz1nKkcYwUjWRG5Q1V7NsW0i5jErlu2NjBXXgy
x-ncp-apigw-signature-v2:iJFK773KH0WwQ79PasqJ+ZGixtpDQ/abS57WGQdld2M=
x-ncp-region_code:KR

Request body
{
   "channelName" : "testchannel",
   "cdn" : {
     "createCdn":true,
      "cdnType":"GLOBAL_EDGE",
      "profileId" : 291,
      "regionType" : "KOREA"
   },
   "qualitySetId" : 12345,
   "useDvr" : true,
   "immediateOnAir" : true,
   "timemachineMin" : 360,
   "envType" : "DEV",
   "outputProtocol" : "LL_HLS",
    "record": {
         "type": "AUTO_UPLOAD",
         "format": "MP4",
         "bucketName": "hls",
         "filePath": "/livestation",
         "accessControl": "PRIVATE"
  },
  "isStreamFailOver": true,
  "drmEnabledYn": true,
      "drm": {
        "siteId": "drm-20231115142326-nHyNw",
        "contentId": "my-Test-Multidrm"
      }
}

4. 채널 정보 조회 (링크)

요청 URL

GET https://livestation.apigw.ntruss.com/api/v2/channels/{channelId}

요청 예시

GET /api/v2/channels/ls-20200323114720-bMoDF
HOST: livestation.apigw.ntruss.com
Content-Type: application/json
x-ncp-apigw-timestamp:1521787414578
x-ncp-iam-access-key:6uxz1nKkcYwUjWRG5Q1V7NsW0i5jErlu2NjBXXgy
x-ncp-apigw-signature-v2:iJFK773KH0WwQ79PasqJ+ZGixtpDQ/abS57WGQdld2M=
x-ncp-region_code:KR

필요한 응답

필드명 타입 설명 비고
channelId String
channelName String
instanceNo String
qualitySetId Integer
qualitySetName String
channelStatus String CREATING, READY, PUBLISH, DELETED, BLOCK, FORCE_BLOCK, FORCE_DELETED
snapshot Object
snapshotId Integer
cdn Object
cdn.cdnType String GLOBAL_CDN, GLOBAL_EDGE
cdn.instanceNo String NO_CDN이면 0
cdn.profileId Integer Global Edge의 프로필 ID NO_CDN이면 0
cdn.statusName String CDN 상태 RUNNING, PUBLISHING, STOPPING, STOPPED, CREATING, CHANGING, CDN_NOT_FOUND
cdn.serviceName String CDN Service Name NO_CDN이면 ""
cdn.cdnDomain String CDN Domain NO_CDN이면 ""
publishUrl String
globalPublishUrl String 해외 송출 지원을 위한 URL
streamKey String
recentPublishStartTime Integer
createdTime Integer
totalPublishSeconds Integer
envType String DEV, STAGE, REAL
callbackEndpoint String
  • 중요해 보이는 키: publishUrl, streamKey

5. 방송 수신 (링크)

요청 URL

GET https://livestation.apigw.ntruss.com/api/v2/channels/{channelId}/serviceUrls?serviceUrlType={serviceUrlType}

요청 예시

GET /api/v2/channels/ls-20200326194008-jk9ld/serviceUrls?serviceUrlType=GENERAL
HOST: livestation.apigw.ntruss.com
Content-Type: application/json
x-ncp-apigw-timestamp:1521787414578
x-ncp-iam-access-key:6uxz1nKkcYwUjWRG5Q1V7NsW0i5jErlu2NjBXXgy
x-ncp-apigw-signature-v2:iJFK773KH0WwQ79PasqJ+ZGixtpDQ/abS57WGQdld2M=
x-ncp-region_code:KR

응답 예시

HTTP/1.1 200 OK
Server: nginx
Date: Wed, 12 Sep 2018 09:53:32 GMT
Content-Type: application/json;charset=utf-8
Connection: keep-alive
Access-Control-Allow-Origin: *
x-ncp-trace-id: 36c9k60om4p3238cpmc9gm4cj4

{
   "content" : [
      {
         "name":"720p-16-9",
         "url":"https://test123.edge.naverncp.com/live/video/ls-20200326194008-jk9ld/720p-16-9/playlist.m3u8",
         "resolution":"1280x720",
         "videoBitrate":"2500000",
         "audioBitrate":"128000"
      },
      {
         "name":"480p-16-9",
         "url":"https://test123.edge.naverncp.com/live/video/ls-20200326194008-jk9ld/480p-16-9/playlist.m3u8",
         "resolution":"854x480",
         "videoBitrate":"1200000",
         "audioBitrate":"128000"
      },
      {
         "name":"360p-16-9",
         "url":"https://test123.edge.naverncp.com/live/video/ls-20200326194008-jk9ld/360p-16-9/playlist.m3u8",
         "resolution":"640x360",
         "videoBitrate":"800000",
         "audioBitrate":"96000"
      },
      {
         "name":"audio-192k",
         "url":"https://test123.edge.naverncp.com/live/video/ls-20200326194008-jk9ld/audio-192k/playlist.m3u8",
         "audioBitrate":"192000"
      },
      {
        "name":"ABR",
         "url":"https://test123.edge.naverncp.com/live/video/ls-20200326194008-jk9ld/playlist.m3u8"
      },
      {
         "name":"dash",
         "url":"https://test123.edge.naverncp.com/live/video/ls-20200326194008-jk9ld/live.mpd"
      }
   ]
}

6. 채널 정지 (링크)

요청 URL

PUT https://livestation.apigw.ntruss.com/api/v2/channels/{channelId}/off

요청 예시

PUT /api/v2/channels/ls-20200323114720-bMoDF/off
HOST: livestation.apigw.ntruss.com
Content-Type: application/json
x-ncp-apigw-timestamp:1521787414578
x-ncp-iam-access-key:6uxz1nKkcYwUjWRG5Q1V7NsW0i5jErlu2NjBXXgy
x-ncp-apigw-signature-v2:iJFK773KH0WwQ79PasqJ+ZGixtpDQ/abS57WGQdld2M=
x-ncp-region_code:KR

7. 채널 삭제 (링크)

요청 URL

DELETE https://livestation.apigw.ntruss.com/api/v2/channels/{channelId}

요청 예시

DELETE /api/v2/channels/ls-20200323114720-bMoDF
HOST: livestation.apigw.ntruss.com
Content-Type: application/json
x-ncp-apigw-timestamp:1521787414578
x-ncp-iam-access-key:6uxz1nKkcYwUjWRG5Q1V7NsW0i5jErlu2NjBXXgy
x-ncp-apigw-signature-v2:iJFK773KH0WwQ79PasqJ+ZGixtpDQ/abS57WGQdld2M=
x-ncp-region_code:KR

8. Global Edge(CDN) 정지 (링크)

요청 URL

POST https://edge.apigw.ntruss.com/api/v1/cdn-edges/stop

요청 예시

DELETE /api/v1/cdn-edges/stop
HOST: edge.apigw.ntruss.com
Content-Type: application/json
x-ncp-apigw-timestamp:1521787414578
x-ncp-iam-access-key:6uxz1nKkcYwUjWRG5Q1V7NsW0i5jErlu2NjBXXgy
x-ncp-apigw-signature-v2:iJFK773KH0WwQ79PasqJ+ZGixtpDQ/abS57WGQdld2M=
x-ncp-region_code:KR

9. Global Edge(CDN) 조회 (링크)

요청 URL

GET https://edge.apigw.ntruss.com/api/v1/cdn-edges/{edgeId}

요청 예시

GET /cdn-edges/{edgeId}
HOST: edge.apigw.ntruss.com/api/v1
Content-Type: application/json
x-ncp-apigw-timestamp:1521787414578
x-ncp-iam-access-key:6uxz1nKkcYwUjWRG5Q1V7NsW0i5jErlu2NjBXXgy
x-ncp-apigw-signature-v2:iJFK773KH0WwQ79PasqJ+ZGixtpDQ/abS57WGQdld2M=

응답 예시

  • 정확한 자료가 없음 (표가 없음) 응답을 살펴본 결과 아래의 내용이 가장 유력함
            "edgeLogging": {
                "enabled": true,
                "bucketPrefix": "log/sample",
                "objectStorage": {
                    "region": "KR",
                    "bucketName": "sample-bucket"
                }
            }

10. Global Edge(CDN) 삭제 (링크)

요청 URL

DELETE https://livestation.apigw.ntruss.com/api/v2/channels/{channelId}

요청 예시

DELETE /api/v2/channels/{channelId}
HOST: livestation.apigw.ntruss.com
Content-Type: application/json
x-ncp-apigw-timestamp:1521787414578
x-ncp-iam-access-key:6uxz1nKkcYwUjWRG5Q1V7NsW0i5jErlu2NjBXXgy
x-ncp-apigw-signature-v2:iJFK773KH0WwQ79PasqJ+ZGixtpDQ/abS57WGQdld2M=

슉(Shook)

📖 룰 & 컨벤션

🌐 API 문서

📑 문서화

💼 모듈화

📱 앱 인터렉션

✏️ 학습 공유

[URL Session]

[ReplayKit]

[Git]

[RTMP]

[기타]

📝 기록

🎨 BI/UX

🔥 PoC

😈 트러블 슈팅

Clone this wiki locally