LiveStreams

Tài nguyên liveStream chứa thông tin về luồng video mà bạn đang truyền đến YouTube. Luồng này cung cấp nội dung sẽ được phát sóng cho người dùng YouTube. Sau khi tạo, tài nguyên liveStream có thể được liên kết với một hoặc nhiều tài nguyên liveBroadcast.

Phương thức

API này hỗ trợ các phương thức sau cho tài nguyên liveStreams:

list
Trả về danh sách các luồng video khớp với các tham số yêu cầu API. Thử ngay.
chèn
Tạo luồng video. Luồng này cho phép bạn gửi video đến YouTube để YouTube có thể phát video đó cho khán giả của bạn. Thử ngay.
update
Cập nhật luồng video. Nếu không thể cập nhật các thuộc tính mà bạn muốn thay đổi, thì bạn cần tạo một luồng mới với chế độ cài đặt thích hợp. Thử ngay.
xóa
Xoá luồng video. Thử ngay.

Biểu diễn tài nguyên

Cấu trúc JSON sau đây cho thấy định dạng của tài nguyên liveStreams:

{
  "kind": "youtube#liveStream",
  "etag": etag,
  "id": string,
  "snippet": {
    "publishedAt": datetime,
    "channelId": string,
    "title": string,
    "description": string,
    "isDefaultStream": boolean
  },
  "cdn": {
    "ingestionType": string,
    "ingestionInfo": {
      "streamName": string,
      "ingestionAddress": string,
      "backupIngestionAddress": string
    },
    "resolution": string,
    "frameRate": string
  },
  "status": {
    "streamStatus": string,
    "healthStatus": {
      "status": string,
      "lastUpdateTimeSeconds": unsigned long,
      "configurationIssues": [
        {
          "type": string,
          "severity": string,
          "reason": string,
          "description": string
        }
      ]
    }
  },
  "contentDetails": {
    "closedCaptionsIngestionUrl": string,
    "isReusable": boolean
  }
}

Thuộc tính

Bảng sau đây xác định các thuộc tính xuất hiện trong tài nguyên này:

Thuộc tính
kind string
Xác định loại tài nguyên API. Giá trị sẽ là youtube#liveStream.
etag etag
Etag của tài nguyên này.
id string
Mã nhận dạng do YouTube gán để nhận dạng riêng luồng đó.
snippet object
Đối tượng snippet chứa thông tin chi tiết cơ bản về sự kiện phát trực tiếp, bao gồm cả kênh, tiêu đề và nội dung mô tả.
snippet.publishedAt datetime
Ngày và giờ tạo luồng. Giá trị được chỉ định ở định dạng ISO 8601 (YYYY-MM-DDThh:mm:ss.sZ).
snippet.channelId string
Mã mà YouTube sử dụng để nhận dạng duy nhất kênh đang truyền phát luồng.
snippet.title string
Tiêu đề của sự kiện phát trực tiếp. Giá trị phải có độ dài từ 1 đến 128 ký tự.
snippet.description string
Nội dung mô tả của luồng. Giá trị không được dài quá 10.000 ký tự.
snippet.isDefaultStream boolean
Thuộc tính này sẽ không được dùng nữa kể từ ngày 1 tháng 9 năm 2020. Khi đó, YouTube sẽ ngừng tạo sự kiện phát trực tiếp và sự kiện phát trực tiếp mặc định khi một kênh được bật tính năng phát trực tiếp. Vui lòng xem thông báo về việc không dùng nữa để biết thêm thông tin chi tiết.
Thuộc tính này cho biết liệu luồng này có phải là luồng mặc định cho kênh hay không.

Cách hoạt động của luồng mặc định

Khi một kênh YouTube được bật tính năng phát trực tiếp, YouTube sẽ tạo một luồng mặc định và một chương trình phát sóng mặc định cho kênh đó. Luồng phát trực tiếp xác định cách chủ sở hữu kênh gửi video phát trực tiếp đến YouTube, còn sự kiện phát trực tiếp là cách người xem có thể xem luồng phát trực tiếp mặc định. Chủ sở hữu kênh có thể sử dụng các phương thức liveStreams.listliveBroadcasts.list để xác định những tài nguyên này.

Luồng mặc định của kênh tồn tại vô thời hạn, không có thời gian bắt đầu hoặc kết thúc liên kết với luồng đó và không thể xoá. Chủ sở hữu kênh chỉ cần bắt đầu gửi các bit video và luồng sẽ tự động tiếp tục.

Khi một sự kiện phát trực tiếp kết thúc, YouTube sẽ chuyển đổi sự kiện phát trực tiếp đã kết thúc thành một video trên YouTube và gán cho video đó một mã video trên YouTube. Sau khi quá trình chuyển đổi hoàn tất, video sẽ được đưa vào danh sách video đã tải lên của kênh. Video không xuất hiện ngay sau khi chương trình phát sóng kết thúc và thời lượng của độ trễ liên quan đến thời lượng thực tế của chương trình phát sóng.
cdn object
Đối tượng cdn xác định chế độ cài đặt mạng phân phối nội dung (CDN) của sự kiện phát trực tiếp. Các chế độ cài đặt này cung cấp thông tin chi tiết về cách bạn truyền trực tuyến nội dung đến YouTube.
cdn.format string
Tính năng này đã ngừng hoạt động kể từ ngày 18 tháng 4 năm 2016 và sẽ không còn được hỗ trợ kể từ ngày 17 tháng 8 năm 2020. Các yêu cầu vẫn sử dụng thuộc tính này như ngày đó sẽ không thành công.

Thay vào đó, hãy sử dụng các thuộc tính cdn.frameRatecdn.resolution để chỉ định tốc độ khung hình và độ phân giải riêng biệt.
cdn.ingestionType string
Phương thức hoặc giao thức dùng để truyền luồng video.

Các giá trị hợp lệ cho thuộc tính này là:
  • dash
  • hls
  • rtmp (bao gồm cả RTMPS)
cdn.ingestionInfo object
Đối tượng ingestionInfo chứa thông tin mà YouTube cung cấp mà bạn cần để truyền luồng của mình đến YouTube.
cdn.ingestionInfo.streamName string
Tên sự kiện phát trực tiếp mà YouTube chỉ định cho sự kiện phát trực tiếp video.
cdn.ingestionInfo.ingestionAddress string
URL truyền dẫn chính mà bạn nên sử dụng để truyền trực tuyến video đến YouTube nếu bạn sử dụng RTMP, DASH hoặc HLS. Bạn phải truyền trực tuyến video đến URL này.

Tuỳ thuộc vào ứng dụng hoặc công cụ bạn sử dụng để mã hoá luồng video, bạn có thể phải nhập URL luồng và tên luồng riêng biệt hoặc có thể phải nối các URL đó theo định dạng sau:
STREAM_URL/STREAM_NAME
cdn.ingestionInfo.backupIngestionAddress string
URL truyền dẫn dự phòng mà bạn nên dùng để truyền trực tuyến video đến YouTube nếu bạn sử dụng RTMP, DASH hoặc HLS. Bạn có thể đồng thời truyền trực tuyến nội dung mà bạn đang gửi đến ingestionAddress đến URL này.
cdn.ingestionInfo.rtmpsIngestionAddress string
URL truyền dẫn chính mà bạn nên sử dụng để truyền trực tuyến video đến YouTube nếu bạn sử dụng RTMPS. Bạn phải phát trực tuyến video đến URL này.

Tuỳ thuộc vào ứng dụng hoặc công cụ bạn sử dụng để mã hoá luồng video, bạn có thể cần nhập URL luồng và tên luồng riêng biệt hoặc bạn có thể cần nối các URL đó theo định dạng sau:
STREAM_URL/STREAM_NAME
cdn.ingestionInfo.rtmpsBackupIngestionAddress string
URL truyền dẫn dự phòng mà bạn nên sử dụng để truyền trực tuyến video đến YouTube nếu bạn sử dụng RTMPS.
cdn.resolution string
Độ phân giải của dữ liệu video đến.

Các giá trị hợp lệ cho thuộc tính này là:
  • 240p
  • 360p
  • 480p
  • 720p
  • 1080p
  • 1440p
  • 2160p
  • variable: Sử dụng chế độ cài đặt này để cho biết YouTube sẽ tự động phát hiện độ phân giải của video phát trực tuyến. Bạn cũng phải đặt cdn.frameRate thành variable.
    Hãy xem các chế độ cài đặt bộ mã hoá được đề xuất trong Trung tâm trợ giúp của YouTube.
cdn.frameRate string
Tốc độ khung hình của dữ liệu video đến.

Các giá trị hợp lệ cho thuộc tính này là:
  • 30fps
  • 60fps
  • variable: Sử dụng chế độ cài đặt này để cho biết rằng YouTube sẽ tự động phát hiện tốc độ khung hình của video phát trực tuyến. Bạn cũng phải đặt cdn.resolution thành variable.
    Hãy xem các chế độ cài đặt bộ mã hoá được đề xuất trong Trung tâm trợ giúp của YouTube.
status object
Đối tượng status chứa thông tin về trạng thái của sự kiện phát trực tiếp.
status.streamStatus string
Trạng thái của luồng.

Các giá trị hợp lệ cho thuộc tính này là:
  • active – Luồng đang ở trạng thái hoạt động, nghĩa là người dùng đang nhận dữ liệu qua luồng.
  • created – Luồng đã được tạo nhưng không có chế độ cài đặt CDN hợp lệ.
  • error – Có điều kiện lỗi trên luồng.
  • inactive – Luồng đang ở trạng thái không hoạt động, tức là người dùng không nhận được dữ liệu qua luồng.
  • ready – Luồng có chế độ cài đặt CDN hợp lệ.
status.healthStatus object
Đối tượng này chứa thông tin về trạng thái hoạt động của sự kiện phát trực tiếp. Bạn có thể dùng thông tin này để xác định, chẩn đoán và giải quyết các vấn đề phát trực tiếp.
status.healthStatus.status string
Mã trạng thái của luồng này.

Các giá trị hợp lệ cho thuộc tính này là:
  • good – Không có vấn đề về cấu hình nào có mức độ nghiêm trọngwarning trở lên.
  • ok – Không có vấn đề về cấu hình nào có mức độ nghiêm trọngerror.
  • bad – Luồng có một số vấn đề với mức độ nghiêm trọngerror.
  • noData – Máy chủ phụ trợ phát trực tiếp của YouTube không có bất kỳ thông tin nào về tình trạng của sự kiện phát trực tiếp.
status.healthStatus.lastUpdateTimeSeconds unsigned long
Lần gần đây nhất trạng thái của luồng được cập nhật. Giá trị này phản ánh dấu thời gian UNIX tính bằng giây.
status.healthStatus.configurationIssues[] list
Đối tượng này chứa danh sách các vấn đề về cấu hình ảnh hưởng đến luồng.
status.healthStatus.configurationIssues[].type string
Xác định loại lỗi ảnh hưởng đến luồng.
status.healthStatus.configurationIssues[].severity string
Cho biết mức độ nghiêm trọng của vấn đề đối với luồng.

Các giá trị hợp lệ cho thuộc tính này là:
  • info – Video được phát sóng cho người xem mà không ảnh hưởng bất lợi đến hiệu suất.
  • warning – Video được phát sóng cho người xem nhưng hiệu suất không tối ưu.
  • error – Không thể phát video cho người xem.
status.healthStatus.configurationIssues[].reason string
Nội dung mô tả ngắn gọn về vấn đề. Tài liệu Các vấn đề về cấu hình đối với tài nguyên LiveStream xác định lý do liên quan đến từng loại vấn đề về cấu hình.
status.healthStatus.configurationIssues[].description string
Nội dung mô tả chi tiết về vấn đề. Khi có thể, nội dung mô tả sẽ cung cấp thông tin về cách giải quyết vấn đề. Tài liệu Vấn đề về cấu hình đối với tài nguyên LiveStream liệt kê tất cả các loại vấn đề về cấu hình và nội dung mô tả liên quan.
contentDetails object
Đối tượng content_details chứa thông tin về luồng, bao gồm cả URL truyền dẫn phụ đề.
contentDetails.closedCaptionsIngestionUrl string
URL truyền dẫn nơi gửi phụ đề của luồng này.
contentDetails.isReusable boolean
Cho biết liệu luồng có thể sử dụng lại hay không, nghĩa là luồng có thể được liên kết với nhiều thông báo truyền tin. Thông thường, các đài truyền hình thường sử dụng lại cùng một luồng cho nhiều chương trình phát sóng nếu các chương trình phát sóng đó diễn ra vào các thời điểm khác nhau.

Nếu bạn đặt giá trị này thành false, thì luồng sẽ không thể sử dụng lại, tức là luồng chỉ có thể liên kết với một thông báo truyền tin. Luồng không thể sử dụng lại khác với luồng có thể sử dụng lại ở những điểm sau:
  • Bạn chỉ có thể liên kết một luồng không thể sử dụng lại với một thông báo truyền tin.
  • Luồng không thể sử dụng lại có thể bị xoá bằng quy trình tự động sau khi sự kiện phát trực tiếp kết thúc.
  • Phương thức liveStreams.list không liệt kê các luồng không thể sử dụng lại nếu bạn gọi phương thức này và đặt tham số mine thành true. Cách duy nhất để sử dụng phương thức đó nhằm truy xuất tài nguyên cho luồng không thể sử dụng lại là sử dụng tham số id để xác định luồng.