Custom 화질 설정 생성

Prev Next

Classic/VPC 환경에서 이용 가능합니다.

원하는 화질을 그룹핑하여 Custom 화질 설정을 생성합니다.

요청

요청 형식을 설명합니다. 요청 형식은 다음과 같습니다.

메서드 URI
POST /api/v2/qualitySets

요청 헤더

Live Station API에서 공통으로 사용하는 헤더에 대한 정보는 Live Station 요청 헤더를 참조해 주십시오.

요청 바디

요청 바디에 대한 설명은 다음과 같습니다.

필드 타입 필수 여부 설명
name String Required 화질 설정 이름
  • 영문자, 숫자, 특수 문자 '-'를 허용하며, 3~20자 이내로 입력
  • 이름 중복 가능
qualityIds Array Required 화질 아이디 목록
  • 최대 4개 입력 가능
  • 1920x1080 해상도의 화질은 1개만 입력 가능
  • 화질 목록 조회 참조
isEnabledUll Boolean Required Low Latency 설정 여부
  • true | false
    • true: LL-HLS (CMAF을 이용한 저지연 HLS 스트리밍을 위한 옵션)
    • false: HLS (안정적이고 호환성 높은 HLS 스트리밍을 이용하기 위한 옵션)
segmentDuration Integer Conditional 세그먼트당 재생 시간(밀리초)
  • 1000~10000
  • 세그먼트 재생 시간이 길면 파일 크기가 커지고 로딩이 길어질 수 있음
  • 세그먼트 재생 시간이 짧으면 파일 크기는 작아지지만, 버퍼링이 발생할 수 있음
  • isEnabledUllfalse인 경우, 필수 입력
segmentCount Integer Conditional 세그먼트 수
  • 2~10
  • 세그먼트 수가 많으면 안정적인 재생이 제공되나 지연 시간과 메모리 사용량이 증가됨
  • 세그먼트 수가 적으면 지연이 적은 반면 안정성이 떨어지고 타임머신 재생 범위가 좁아짐
  • isEnabledUllfalse인 경우, 필수 입력
enableHlsTimedMetadata Boolean Required 시간 기반 메타데이터 설정 여부
  • true | false
    • true: 설정
    • false: 설정 안 함
  • 설정 시 timedMetadata.interval마다 각 세그먼트에 메타데이터 삽입
timedMetadata Object Conditional 시간 기반 메타데이터 설정
  • enableHlsTimedMetadatatrue인 경우, 필수 입력
timedMetadata.header String Conditional 헤더(식별 값)
  • 1~128자 이내로 입력
timedMetadata.interval Integer Conditional 삽입 주기(밀리초)
  • 1000 (유효 값)
timedMetadata.key String Conditional
  • utc (유효 값)

요청 예시

요청 예시는 다음과 같습니다.

curl --location --request POST 'https://livestation.apigw.ntruss.com/api/v2/qualitySets' \
--header 'x-ncp-apigw-timestamp: {Timestamp}' \
--header 'x-ncp-iam-access-key: {Access Key}' \
--header 'x-ncp-apigw-signature-v2: {API Gateway Signature}' \
--header 'Content-Type: application/json' \
--header 'x-ncp-region_code: KR' \
--data '{
    "name": "setting000",
    "qualityIds": [
        ****, 5
    ],
    "isEnabledUll": false,
    "segmentDuration": 1000,
    "segmentCount": 2,
    "enableHlsTimedMetadata": true,
    "timedMetadata": {
        "header": "ncloud.livestation.metadata",
        "interval": 1000,
        "key": "utc"
    }
}'

응답

응답 형식을 설명합니다.

응답 바디

응답 바디에 대한 설명은 다음과 같습니다.

필드 타입 필수 여부 설명
content Object - 응답 결과
content.disabled Boolean - 화질 비활성화 여부
  • true | false
    • true: 비활성
    • false: 활성
content.id Integer - 화질 설정 아이디
content.status String - 화질 설정 상태
  • CREATED: 생성 완료 (유효 값)
content.createdTime Integer - 화질 설정 생성 일시(밀리초)
  • Unix Timestamp 형식
content.genType String - 설정 분류
  • CUSTOM | SYSTEM
    • CUSTOM: 직접 생성
    • SYSTEM: 기본 제공
content.name String - 화질 설정 이름
content.segmentDuration Integer - 세그먼트당 재생 시간(밀리초)
  • 세그먼트 재생 시간이 길면 파일 크기가 커지고 로딩이 길어질 수 있음
  • 세그먼트 재생 시간이 짧으면 파일 크기는 작아지지만, 버퍼링이 발생할 수 있음
  • content.isEnabledUllfalse인 경우, 표시
content.segmentCount Integer - 세그먼트 수
  • 세그먼트 수가 많으면 안정적인 재생이 제공되나 지연 시간과 메모리 사용량이 증가됨
  • 세그먼트 수가 적으면 지연이 적은 반면 안정성이 떨어지고 타임머신 재생 범위가 좁아짐
  • content.isEnabledUllfalse인 경우, 표시
content.qualityIds Array - 화질 아이디 목록
content.qualities Array - 화질 목록: qualities
content.enableHlsTimedMetadata Boolean - 시간 기반 메타데이터 설정 여부
  • true | false
    • true: 설정
    • false: 설정 안 함
content.isEnabledUll Boolean - Low Latency 설정 여부
  • true | false
    • true: LL-HLS (CMAF을 이용한 저지연 HLS 스트리밍을 위한 옵션)
    • false: HLS (안정적이고 호환성 높은 HLS 스트리밍을 이용하기 위한 옵션)
content.targetLatency Integer - Low Latency 목표 지연 시간(초)
  • isEnabledUlltrue인 경우, 표시
content.timedMetadata Object - 시간 기반 메타데이터 설정
  • enableHlsTimedMetadatatrue인 경우, 표시
content.timedMetadata.key String -
  • utc (유효 값)
content.timedMetadata.header String - 헤더(식별 값)
content.timedMetadata.interval Integer - 삽입 주기(밀리초)
  • 1000 (유효 값)

qualities

qualities에 대한 설명은 다음과 같습니다.

필드 타입 필수 여부 설명
disabled Boolean - 화질 비활성화 여부
  • true | false
    • true: 비활성
    • false: 활성
id Integer - 화질 아이디
status String - 화질 상태
  • CREATED: 생성 완료 (유효 값)
createdTime Integer - 화질 생성 일시(밀리초)
  • Unix Timestamp 형식
genType String - 설정 분류
  • CUSTOM | SYSTEM
    • CUSTOM: 직접 생성
    • SYSTEM: 기본 제공
name String - 화질 이름
type String - 화질 타입
  • NORMAL | AUDIO | BYPASS
    • NORMAL: 비디오, 오디오 출력
    • AUDIO: 오디오 전용 출력
    • BYPASS: 원본 출력 설정에 따름
video Object - 비디오 설정 정보
  • typeAUDIO인 경우, 하위 정보 포함하여 미표시
video.fps Float - 초당 프레임 수(fps)
video.bitrate Integer - 비디오 스트림의 비트레이트(bps)
video.bframes Integer - B-프레임(양방향 예측 프레임) 수
video.level Integer - 비디오 코덱 레벨
  • -1: AUTO (유효 값)
  • 재생(디코딩)에 필요한 하드웨어의 성능 한계치를 미리 정의해 둔 표준 명세
video.width Integer - 출력 비디오의 너비(픽셀)
video.height Integer - 출력 비디오의 높이(픽셀)
video.bypass Boolean - 비디오 스트림 바이패스 여부
  • true | false
    • true: 원본 스트림 그대로 사용(pass-through)
    • false: 설정 정보에 맞춰 트랜스코딩
video.codec String - 비디오 코덱 포맷
  • H264 (유효 값)
video.orientation String - 비디오 방향 전환 설정
  • FIX | FREE
    • FIX: 고정
    • FREE: 전환 가능
video.profile String - 비디오 코덱 프로필
  • BASELINE | MAIN | HIGH
    • BASELINE: 기본 옵션(저사양 단말용, 최소 기능 제공)
    • MAIN: HD 권장 옵션
    • HIGH: Full HD 권장 옵션
  • 비디오의 사용 용도에 맞게 H.264 코덱의 특정 기술을 사용할 수 있도록 미리 정의해 둔 표준 명세
video.rateControl String - 비트레이트 배분 방식
  • VBR | CBR
    • VBR: 가변 비트레이트(Variable Bitrate)
    • CBR: 고정 비트레이트(Constant Bitrate)
video.videoH264ParamRefFrames Integer - H.264 참조 프레임 수
  • 1 (유효 값)
audio Object - 오디오 설정 정보
audio.codec String - 오디오 코덱 포맷
  • AAC | MP3
audio.profile String - 오디오 코덱 프로필
  • LC: AAC-LC (유효 값)
audio.samplerate Integer - 오디오 샘플링 레이트(Hz)
  • 초당 샘플링 수
audio.channels Integer - 오디오 채널 수
audio.bitrate Integer - 오디오 스트림의 비트레이트(Kbps)
audio.bypass Boolean - 오디오 스트림 바이패스 여부
  • true | false
    • true: 원본 스트림 그대로 사용(pass-through)
    • false: 설정 정보에 맞춰 트랜스코딩

응답 상태 코드

Live Station API에서 공통으로 사용하는 응답 상태 코드에 대한 정보는 Live Station 응답 상태 코드를 참조해 주십시오.

응답 예시

응답 예시는 다음과 같습니다.

{
    "content": {
        "disabled": false,
        "id": ****,
        "status": "CREATED",
        "createdTime": 1755138264367,
        "genType": "CUSTOM",
        "name": "setting000",
        "segmentDuration": 1000,
        "segmentCount": 2,
        "qualityIds": [
            5,
            ****
        ],
        "qualities": [
            {
                "disabled": false,
                "id": 5,
                "status": "CREATED",
                "createdTime": 1546300800000,
                "genType": "SYSTEM",
                "name": "720p-9-16",
                "type": "NORMAL",
                "video": {
                    "fps": 30.0,
                    "bitrate": 2500000,
                    "bframes": 0,
                    "level": -1,
                    "width": 720,
                    "height": 1280,
                    "bypass": false,
                    "codec": "H264",
                    "profile": "MAIN",
                    "rateControl": "VBR",
                    "videoH264ParamRefFrames": 1
                },
                "audio": {
                    "codec": "AAC",
                    "profile": "LC",
                    "samplerate": 48000,
                    "channels": 0,
                    "bitrate": 128,
                    "bypass": false
                }
            },
            {
                "disabled": false,
                "id": ****,
                "status": "CREATED",
                "createdTime": 1755134604000,
                "genType": "CUSTOM",
                "name": "quality000",
                "type": "NORMAL",
                "video": {
                    "fps": 60.0,
                    "bitrate": 204800000,
                    "bframes": 4,
                    "level": -1,
                    "width": 1920,
                    "height": 1080,
                    "bypass": true,
                    "codec": "H264",
                    "profile": "HIGH",
                    "rateControl": "VBR",
                    "videoH264ParamRefFrames": 1
                },
                "audio": {
                    "codec": "AAC",
                    "profile": "LC",
                    "samplerate": 44100,
                    "channels": 2,
                    "bitrate": 320,
                    "bypass": true
                }
            }
        ],
        "enableHlsTimedMetadata": true,
        "isEnabledUll": false,
        "timedMetadata": {
            "key": "utc",
            "header": "ncloud.livestation.metadata",
            "interval": 1000
        }
    }
}