Registrazione composita in IVS I Streaming in tempo reale

Questo documento spiega come utilizzare la funzionalità di registrazione composita all'interno della composizione lato server. La registrazione composita consente di generare registrazioni HLS di una fase IVS combinando efficacemente tutti i publisher della fase in un'unica visualizzazione utilizzando un server IVS e quindi salvando il video risultante in un bucket S3.

Si applicano i costi standard di archiviazione e richiesta di Amazon S3. Le miniature non comportano costi IVS aggiuntivi. Per ulteriori dettagli, consulta la pagina Prezzi di Amazon IVS.

Prerequisiti

Per utilizzare la registrazione composita, è necessario disporre di una fase con publisher attivi e di un bucket S3 da utilizzare come destinazione di registrazione. Di seguito, descriviamo un possibile flusso di lavoro che utilizza gli eventi EventBridge per registrare una composizione in un bucket S3. In alternativa, puoi avviare e interrompere le composizioni in base alla logica della tua applicazione.

Nota: una composizione si spegne automaticamente dopo 60 secondi di inattività dei publisher che partecipano alla fase. A quel punto, la composizione viene terminata e passa a uno stato STOPPED. Una composizione viene eliminata automaticamente dopo alcuni minuti nello stato STOPPED. Per i dettagli, consulta Ciclo di vita della composizione in Composizione lato server.

Esempio di registrazione composita: StartComposition con una destinazione di bucket S3

L'esempio seguente mostra una chiamata tipica all'operazione StartComposition, che specifica S3 come unica destinazione per la composizione. Una volta che la composizione passa a uno stato ACTIVE, i segmenti video e i metadati inizieranno a essere scritti nel bucket S3 specificato dall'oggetto storageConfiguration. Per creare composizioni con layout diversi, consulta "Layout" in Composizione lato server e la Documentazione di riferimento delle API dello streaming in tempo reale IVS.

Richiesta

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",
	    "thumbnailConfigurations": [
	       {
		  "storage": ["LATEST", "SEQUENTIAL"],
		  "targetIntervalSeconds": 30
               }
	    ]
	 }
      }
   ],
   "idempotencyToken": "db1i782f1g9",
   "stageArn": "arn:aws:ivs:ap-northeast-1:927810967299:stage/WyGkzNFGwiwr"
}

Risposta

{
    "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",
	                "thumbnailConfigurations": [
	                   {
		              "storage": ["LATEST", "SEQUENTIAL"],
		              "targetIntervalSeconds": 30
                           }
	                ]
                    }
                },
                "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": {}
    }
}

Il campo recordingPrefix, presente nella risposta di StartComposition, può essere utilizzato per determinare dove verranno archiviati i contenuti della registrazione.

Contenuto della registrazione

Quando la composizione passa a uno stato ACTIVE, i segmenti video, i file di metadati e le miniature (se configurate) HLS verranno scritti nel bucket S3 fornito durante la chiamata StartComposition. Questo contenuto è disponibile per la post-elaborazione o la riproduzione come video on demand.

Tieni presente che dopo che una composizione diventa attiva, viene emesso un evento "Cambia stato della composizione IVS" ed è possibile che passi del tempo prima che i file manifesto, i segmenti video e le anteprime vengano scritti. Consigliamo di riprodurre o elaborare flussi registrati solo dopo che è stato ricevuto l'evento "Modifica dello stato di composizione dell'IVS (Fine sessione)". Per maggiori dettagli, consulta Utilizzo di EventBridge con lo streaming in tempo reale IVS.

Di seguito è riportato un esempio di contenuti e della struttura di directory di una registrazione di una sessione IVS live:

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

La cartella events contiene i file di metadati corrispondenti all'evento di registrazione. I file di metadati JSON vengono generati quando la registrazione inizia, termina correttamente o termina con errori:

Una determinata cartella events conterrà recording-started.json e recording-ended.json o recording-failed.json.

Questi contengono metadati relativi alla sessione registrata e ai relativi formati di output. I dettagli JSON sono riportati di seguito.

La cartella media contiene i contenuti multimediali supportati. La sottocartella hls contiene tutti i file multimediali e i file manifesto generati durante la sessione della composizione ed è riproducibile con il lettore IVS. Il manifesto HLS si trova nella cartella multivariant.m3u8. Se configurate, le sottocartelle thumbnails e latest_thumbnail contengono file multimediali in miniatura JPEG generati durante la sessione di composizione.

Policy del bucket per StorageConfiguration

Quando viene creato un oggetto StorageConfiguration, IVS avrà accesso alla scrittura di contenuti nel bucket S3 specificato. Questo accesso viene concesso apportando modifiche alla policy del bucket S3. Se la policy per il bucket viene modificata in modo da rimuovere l'accesso di IVS, le registrazioni in corso e quelle nuove avranno esito negativo.

L'esempio seguente mostra una policy di bucket S3 che consente a IVS di scrivere nel bucket 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"
                }
            }
        }
    ]
}

File di metadati JSON

Questi metadati sono in formato JSON. Tale controllo contiene le seguenti informazioni:

Esempio: 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
        }
      ]
    },
    "thumbnails": {
      "path": "media/thumbnails",
      "resolutions": [
        {
          "path": "1280x720",
          "resolution_width": 1280,
          "resolution_height": 720
        }
      ]
    },
    "latest_thumbnail": {
      "path": "media/latest_thumbnail",
      "resolutions": [
        {
          "path": "1280x720",
          "resolution_width": 1280,
          "resolution_height": 720
        }
      ]
    }
  }
}

Esempio: 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
        }
      ]
    },
    "thumbnails": {
      "path": "media/thumbnails",
      "resolutions": [
        {
          "path": "1280x720",
          "resolution_width": 1280,
          "resolution_height": 720
        }
      ]
    },
    "latest_thumbnail": {
      "path": "media/latest_thumbnail",
      "resolutions": [
        {
          "path": "1280x720",
          "resolution_width": 1280,
          "resolution_height": 720
        }
      ]
    }
  }
}

Esempio: 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
        }
      ]
    },
    "thumbnails": {
      "path": "media/thumbnails",
      "resolutions": [
        {
          "path": "1280x720",
          "resolution_width": 1280,
          "resolution_height": 720
        }
      ]
    },
    "latest_thumbnail": {
      "path": "media/latest_thumbnail",
      "resolutions": [
        {
          "path": "1280x720",
          "resolution_width": 1280,
          "resolution_height": 720
        }
      ]
    }
  }
}

Riproduzione di contenuti registrati da bucket privati

Per impostazione predefinita, il contenuto registrato è privato, pertanto questi oggetti sono inaccessibili per la riproduzione direttamente tramite l'URL S3. Se provi ad aprire la playlist multivariata HLS (file m3u8) per la riproduzione utilizzando il lettore IVS o un altro lettore, riceverai un errore (ad esempio, "Non disponi dell'autorizzazione per accedere alla risorsa richiesta"). Pertanto, è possibile riprodurre questi file con Amazon CloudFront CDN (Content Delivery Network).

Le distribuzioni CloudFront possono essere configurate in modo da distribuire i contenuti da bucket privati. Generalmente, è preferibile disporre di bucket accessibili in modo aperto in cui le letture ignorano i controlli offerti da CloudFront. La tua distribuzione può essere configurata in modo da funzionare da un bucket privato creando un controllo degli accessi all'origine (OAC), ovvero un utente CloudFront speciale che dispone delle autorizzazioni di lettura sul bucket di origine privato. Puoi creare l'OAC dopo aver creato la distribuzione tramite la console CloudFront o l'API. Consulta Creazione di un nuovo controllo di accesso di origine nella Guida per gli sviluppatori di Amazon CloudFront.

Configurazione della riproduzione tramite CloudFront con CORS abilitato

Questo esempio illustra come uno sviluppatore può configurare una distribuzione CloudFront con CORS abilitato, consentendo la riproduzione delle proprie registrazioni da qualsiasi dominio. Ciò è particolarmente utile durante la fase di sviluppo, ma è possibile modificare l'esempio seguente per adattarlo alle proprie esigenze di produzione.

Fase 1: creazione di un bucket S3

Crea un bucket S3 che verrà utilizzato per archiviare le registrazioni. Tieni presente che il bucket dovrà trovarsi nella stessa Regione utilizzata per il flusso di lavoro IVS.

Aggiungi una policy CORS di autorizzazione al bucket:

Passaggio 2: Creare una distribuzione CloudFront

Consulta Creazione di una distribuzione CloudFront nella Guida per gli sviluppatori di CloudFront.

Dalla console AWS, immetti le seguenti informazioni aziendali:

Quindi salva la distribuzione CloudFront.

Fase 3: Configurazione della policy del bucket S3

Dopo aver creato StorageConfiguration, nella policy del bucket S3 verranno visualizzati due elementi, uno che consente a CloudFront di leggere i contenuti e l'altro che consente a IVS di scrivere contenuti. Un esempio di policy del bucket finale, con accesso a CloudFront e IVS, è riportato in Esempio: Policy del bucket S3 con accesso a CloudFront e IVS.

Fase 4: Riproduzione delle registrazioni

Dopo aver configurato correttamente la distribuzione CloudFront e aggiornato la policy del bucket, dovresti essere in grado di riprodurre le registrazioni utilizzando il lettore IVS:

Esempio: Policy del bucket S3 con accesso a CloudFront e IVS

Il frammento di codice riportato di seguito illustra una policy del bucket S3 che consente a CloudFront di leggere i contenuti nel bucket privato e a IVS di scrivere contenuti nel bucket. Nota: non copiare e incollare il frammento di codice riportato di seguito nel tuo bucket. La policy deve contenere gli ID pertinenti alla distribuzione CloudFront e a StorageConfiguration

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

Risoluzione dei problemi

Problema noto

La playlist multimediale scritta mediante registrazione composita ha il tag #EXT-X-PLAYLIST-TYPE:EVENT mentre la composizione è in corso. Al termine della composizione, il tag viene aggiornato a #EXT-X-PLAYLIST-TYPE:VOD. Per un'esperienza di riproduzione fluida, ti consigliamo di utilizzare questa playlist solo dopo che la composizione è stata completata con successo.