IVS 레코딩 | 실시간 스트리밍

이 문서에서는 서버 측 구성 내에서 복합 레코딩 기능을 사용하는 방법을 설명합니다. 복합 레코딩을 사용하면 IVS 서버를 사용하여 하나의 보기로 모든 스테이지 게시자를 효과적으로 결합한 다음 결과 비디오를 S3 버킷에 저장함으로써 IVS 스테이지의 HLS 레코딩을 생성할 수 있습니다.

사전 조건

복합 레코딩을 사용하려면 활성 게시자가 있는 스테이지와 레코딩 대상으로 사용할 S3 버킷이 있어야 합니다. 아래에서는 EventBridge 이벤트를 사용하여 S3 버킷에 구성을 레코드 할 수 있는 한 가지 워크플로를 설명합니다. 그 대신 자체 앱 로직에 따라 구성을 시작하고 중지할 수 있습니다.

참고: 스테이지에 있는 게시자 참가자가 60초 동안 활동이 없으면 구성이 자동 종료됩니다. 이때 구성이 종료되고 STOPPED 상태로 전환합니다. STOPPED 상태로 몇 분 지나면 구성을 자동으로 삭제합니다. 자세한 내용은 서버 측 구성의 구성 수명 주기를 참조하세요.

복합 레코딩 예제: S3 버킷 대상과 StartComposition

아래 예제는 S3를 구성의 유일한 대상으로 지정하는 StartComposition 엔드포인트에 대한 일반적인 호출을 보여줍니다. 구성이 ACTIVE 상태로 전환되면 비디오 세그먼트와 메타데이터가 storageConfiguration 객체가 지정한 S3 버킷에 기록되기 시작합니다. 레이아웃이 다른 구성을 생성하려면 서버 측 구성의 “레이아웃” 및 IVS 실시간 스트리밍 API 참조를 참조하세요.

요청

POST /StartComposition HTTP/1.1
Content-type: application/json

{
   "destinations": [
      {
         "s3": {
            "encoderConfigurationArns": [
              "arn:aws:ivs:ap-northeast-1:927810967299:encoder-configuration/PAAwglkRtjge"
            ],
            "storageConfigurationArn": "arn:aws:ivs:ap-northeast-1:927810967299:storage-configuration/ZBcEbgbE24Cq"
         }
      }
   ],
   "idempotencyToken": "db1i782f1g9",
   "stageArn": "arn:aws:ivs:ap-northeast-1:927810967299:stage/WyGkzNFGwiwr"
}

응답

{
    "composition": {
        "arn": "arn:aws:ivs:ap-northeast-1:927810967299:composition/s2AdaGUbvQgp",
        "destinations": [
            {
                "configuration": {
                    "name": "",
                    "s3": {
                        "encoderConfigurationArns": [
                            "arn:aws:ivs:ap-northeast-1:927810967299:encoder-configuration/PAAwglkRtjge"
                        ],
                        "recordingConfiguration": {
                            "format": "HLS"
                        },
                        "storageConfigurationArn": "arn:aws:ivs:ap-northeast-1:927810967299:storage-configuration/ZBcEbgbE24Cq"
                    }
                },
                "detail": {
                    "s3": {
                        "recordingPrefix": "MNALAcH9j2EJ/s2AdaGUbvQgp/2pBRKrNgX1ff/composite"
                    }
                },
                "id": "2pBRKrNgX1ff",
                "state": "STARTING"
            }
        ],
        "layout": null,
        "stageArn": "arn:aws:ivs:ap-northeast-1:927810967299:stage/WyGkzNFGwiwr",
        "startTime": "2023-11-01T06:25:37Z",
        "state": "STARTING",
        "tags": {}
    }
}

StartComposition 응답에 있는 recordingPrefix 필드를 사용하여 레코딩 콘텐츠를 저장할 위치를 결정할 수 있습니다.

레코딩 콘텐츠

구성이 ACTIVE 상태로 전환되면 StartComposition을 호출할 때 제공된 S3 버킷에 HLS 비디오 세그먼트와 메타데이터 파일이 기록되는 것을 볼 수 있습니다. 이러한 콘텐츠는 온디맨드 비디오로 후처리 또는 재생에 사용할 수 있습니다.

구성이 활성화되면 “IVS 구성 상태 변경” 이벤트가 생성되며 매니페스트 파일과 비디오 세그먼트가 기록되기까지 약간의 시간이 걸립니다. "IVS 구성 상태 변경(레코딩 종료)" 이벤트를 받은 후에 레코딩된 스트림을 재생하거나 처리하는 것이 좋습니다. 자세한 내용은 IVS 실시간 스트리밍과 함께 Amazon EventBridge 사용을 참조하세요.

다음은 라이브 IVS 세션 레코딩의 샘플 디렉터리 구조 및 콘텐츠입니다.

MNALAcH9j2EJ/s2AdaGUbvQgp/2pBRKrNgX1ff/composite
   events
      recording-started.json
      recording-ended.json
   media
      hls

events 폴더에는 레코딩 이벤트에 해당하는 메타데이터 파일이 들어 있습니다. JSON 메타데이터 파일은 레코딩이 시작되거나, 성공적으로 종료되거나, 실패로 종료될 때 생성됩니다.

지정된 events 폴더에는 recording-started.json 및 recording-ended.json 또는 recording-failed.json이 포함됩니다.

여기에는 레코딩된 세션 및 출력 형식과 관련된 메타데이터가 포함됩니다. 다음은 JSON 세부 정보입니다.

media 폴더에는 지원되는 미디어 콘텐츠가 있습니다. hls 하위 폴더에는 구성 세션 중에 생성된 모든 미디어 및 매니페스트 파일이 포함되어 있으며, 이는 IVS 플레이어에서 재생할 수 있습니다. HLS 매니페스트는 multivariant.m3u8 폴더에 있습니다.

StorageConfiguration을 위한 버킷 정책

StorageConfiguration 객체가 생성되면 IVS는 지정된 S3 버킷에 콘텐츠를 쓸 수 있는 액세스 권한을 얻습니다. 이 액세스는 S3 버킷의 정책을 수정하여 부여됩니다. IVS의 액세스를 제거하는 방식으로 버킷 정책을 변경하면 진행 중인 레코딩과 새 레코딩이 실패합니다.

아래 예는 IVS 가 S3 버킷에 기록할 수 있도록 허용하는 S3 버킷 정책을 보여줍니다.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "CompositeWrite-y1d212y",
            "Effect": "Allow",
            "Principal": {
                "Service": "ivs-composite.ap-northeast-1.amazonaws.com"
            },
            "Action": [
                "s3:PutObject",
                "s3:PutObjectAcl"
            ],
            "Resource": "arn:aws:s3:::my-s3-bucket/*",
            "Condition": {
                "StringEquals": {
                    "s3:x-amz-acl": "bucket-owner-full-control"
                },
                "Bool": {
                    "aws:SecureTransport": "true"
                }
            }
        }
    ]
}

JSON 메타데이터 파일

이 메타데이터는 JSON 형식입니다. 이는 다음 정보로 구성됩니다.

예: recording-started.json

{
  "version": "v1",
  "stage_arn": "arn:aws:ivs:ap-northeast-1:123456789012:stage/aAbBcCdDeE12",
  "recording_started_at": "2023-11-01T06:01:36Z",
  "recording_status": "RECORDING_STARTED",
  "media": {
    "hls": {
      "path": "media/hls",
      "playlist": "multivariant.m3u8",
      "renditions": [
        {
          "path": "720p30-abcdeABCDE12",
          "playlist": "playlist.m3u8",
          "resolution_width": 1280,
          "resolution_height": 720
        }
      ]
    }
  }
}

예: recording-ended.json

{
  "version": "v1",
  "stage_arn": "arn:aws:ivs:ap-northeast-1:123456789012:stage/aAbBcCdDeE12",
  "recording_started_at": "2023-10-27T17:00:44Z",
  "recording_ended_at": "2023-10-27T17:08:24Z",
  "recording_status": "RECORDING_ENDED",
  "media": {
    "hls": {
      "duration_ms": 460315,
      "path": "media/hls",
      "playlist": "multivariant.m3u8",
      "renditions": [
        {
          "path": "720p30-abcdeABCDE12",
          "playlist": "playlist.m3u8",
          "resolution_width": 1280,
          "resolution_height": 720
        }
      ]
    }
  }
}

예: recording-failed.json

{
  "version": "v1",
  "stage_arn": "arn:aws:ivs:ap-northeast-1:123456789012:stage/aAbBcCdDeE12",
  "recording_started_at": "2023-10-27T17:00:44Z",
  "recording_ended_at": "2023-10-27T17:08:24Z",
  "recording_status": "RECORDING_ENDED_WITH_FAILURE",
  "media": {
    "hls": {
      "duration_ms": 460315,
      "path": "media/hls",
      "playlist": "multivariant.m3u8",
      "renditions": [
        {
          "path": "720p30-abcdeABCDE12",
          "playlist": "playlist.m3u8",
          "resolution_width": 1280,
          "resolution_height": 720
        }
      ]
    }
  }
}

프라이빗 버킷에서 레코딩된 콘텐츠 재생

기본적으로 레코딩된 콘텐츠는 프라이빗이므로 직접 S3 URL을 사용하여 재생할 수 없습니다. IVS 플레이어나 다른 플레이어를 사용하여 재생할 HLS 다변량 재생 목록(m3u8 파일)을 열려고 하면 오류가 발생합니다(예: “요청한 리소스에 액세스할 수 있는 권한이 없습니다”). 대신 이러한 파일은 Amazon CloudFront 콘텐츠 전송 네트워크(CDN)를 사용하여 재생할 수 있습니다.

프라이빗 버킷의 콘텐츠를 제공하도록 CloudFront 배포를 구성할 수 있습니다. 일반적으로 읽기에서 CloudFront가 제공하는 제어를 우회하는 공개적으로 액세스 가능한 버킷을 사용하는 것을 권장합니다. 프라이빗 원본 버킷에 대한 읽기 권한이 있는 특수한 CloudFront 사용자인 원본 액세스 제어(OAC)를 생성하여 프라이빗 버킷을 통해 서비스를 제공하도록 배포를 설정할 수 있습니다. 배포를 생성한 후 CloudFront 콘솔 또는 API를 통해 OAI를 생성할 수 있습니다. Amazon CloudFront 개발자 안내서의 새 원본 액세스 제어 생성을 참조하세요.

CORS가 활성화된 상태에서 CloudFront를 사용하여 재생 설정

이 예제에서는 개발자가 CORS가 활성화된 상태에서 CloudFront 배포를 설정하여 모든 도메인에서 레코딩을 재생할 수 있는 방법을 설명합니다. 이는 개발 단계에서 특히 유용하지만 프로덕션 요구 사항에 맞게 아래 예제를 수정할 수 있습니다.

1단계: S3 버킷 생성

레코딩을 저장하는 데 사용할 S3 버킷을 생성합니다. 버킷은 IVS 워크플로에 사용하는 것과 동일한 리전에 있어야 합니다.

버킷에 허용 CORS 정책 추가

2단계: CloudFront 배포 생성

CloudFront 개발자 안내서의 CloudFront 배포 생성을 참조하세요.

AWS 콘솔을 사용하여 다음 정보를 입력합니다.

그런 다음 CloudFront 배포를 저장합니다.

3단계: S3 버킷 정책 설정

StorageConfiguration이 생성되면 S3 버킷 정책에 두 개의 항목이 표시됩니다. 하나는 CloudFront가 콘텐츠를 읽도록 허용하고 다른 하나는 IVS가 콘텐츠를 쓰도록 허용합니다. CloudFront 및 IVS 액세스를 포함하는 최종 버킷 정책의 예는 예: CloudFront와 IVS 액세스를 사용하는 S3 버킷 정책에 나와 있습니다.

4단계: 레코딩 재생

CloudFront 배포를 성공적으로 설정하고 버킷 정책을 업데이트한 후에는 IVS 플레이어를 사용하여 녹음를 재생할 수 있어야 합니다.

예: CloudFront 및 IVS 액세스를 사용하는 S3 버킷 정책

아래 코드 조각은 CloudFront가 프라이빗 버킷에 콘텐츠를 읽고 IVS가 버킷에 콘텐츠를 기록할 수 있도록 허용하는 S3 버킷 정책을 보여줍니다. 참고: 아래 코드 조각을 복사하여 자체 버킷에 붙여넣지 마세요. 정책에는 CloudFront 배포 및 StorageConfiguration과 관련된 ID가 포함되어야 합니다.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "CompositeWrite-7eiKaIGkC9DO",
      "Effect": "Allow",
      "Principal": {
        "Service": "ivs-composite.ap-northeast-1.amazonaws.com"
      },
      "Action": [
        "s3:PutObject",
        "s3:PutObjectAcl"
      ],
      "Resource": "arn:aws:s3:::eicheane-test-1026-2-ivs-recordings/*",
      "Condition": {
        "StringEquals": {
          "s3:x-amz-acl": "bucket-owner-full-control"
        },
        "Bool": {
          "aws:SecureTransport": "true"
        }
      }
    },
    {
      "Sid": "AllowCloudFrontServicePrincipal",
      "Effect": "Allow",
      "Principal": {
        "Service": "cloudfront.amazonaws.com"
      },
      "Action": "s3:GetObject",
      "Resource": "arn:aws:s3:::eicheane-test-1026-2-ivs-recordings/*",
      "Condition": {
        "StringEquals": {
          "AWS:SourceArn": "arn:aws:cloudfront::844311324168:distribution/E1NG4YMW5MN25A"
        }
      }
    }
  ]
}

문제 해결

알려진 문제

구성 진행 중에는 복합 레코딩으로 작성된 미디어 재생 목록에 #EXT-X-PLAYLIST-TYPE:EVENT 태그가 붙습니다. 구성이 완료되면 태그가 #EXT-X-PLAYLIST-TYPE:VOD로 업데이트됩니다. 원활한 재생 환경을 위해 구성이 성공적으로 완료된 후에만 이 재생 목록을 사용하는 것이 좋습니다.