Phát nội dung media

Đường dẫn media

GET <baseUrl>/media/<externalId>?t=<mediaToken>

Địa chỉ được dựng như thế nào

Stage dựng địa chỉ từ baseUrl bạn đồng bộ lần gần nhất và externalId của track, và dựng như sau:

• Chỉ origin của baseUrl được dùng: scheme, host và port. Đường dẫn trong baseUrl bị bỏ đi, nên route luôn là /media/… ở gốc của origin đó, chứ không phải /music/media/… chỉ vì bạn gắn nó ở đó.
• externalId được mã hóa phần trăm vào đoạn đường dẫn cuối. Hãy giải mã nó. Một id có dấu cách hoặc dấu gạch chéo sẽ đến dưới dạng %20 hoặc %2F.
• t mang media token, và một bản nghe thử thêm &preview=1 (xem Trả lời theo yêu cầu).
• Địa chỉ được xác định khi một bài sắp phát, từ những gì bạn đồng bộ gần nhất. Stage sau đó giữ nó trong suốt bài đó.

Chứng chỉ của host phải là chứng chỉ mà trình duyệt của Stage đã tin cậy sẵn. Stage là một trang web và không có ai để bấm qua một cảnh báo, nên chứng chỉ tự ký không dùng được, dù cài thế nào. Một provider trong mạng gia đình có thể dùng cái tên và chứng chỉ mô tả trong Một cái tên và một chứng chỉ.

Phải trả lời ra sao

• Từ chối token sai hoặc thiếu bằng 403. Một id bạn không có là 404.
• Hỗ trợ yêu cầu range. Các phần tử media tua bằng chúng. Một máy chủ bỏ qua Range thường phát được một lần rồi hỏng ngay khi có ai kéo thanh tua. Các dạng trình duyệt gửi là bytes=N- và bytes=N-M. Trả lời một range bằng 206, một Content-Range, và Content-Length của phần được trả chứ không phải của cả tệp. Trả lời một range bắt đầu quá cuối tệp bằng 416 và Content-Range: bytes */<size>. Không có header Range thì trả 200 với cả tệp. Gửi Accept-Ranges: bytes trên mọi phản hồi.
• Gửi đúng Content-Type cho container: video/mp4, video/webm, video/quicktime, audio/mpeg, audio/mp4. Trình duyệt đôi khi cứu được một giá trị sai và đôi khi không, và không đáng để thử trên tivi của người ta.
• Trả lời OPTIONS bằng 204 và các header CORS bên dưới. Các yêu cầu của Stage là yêu cầu đơn giản, nên không mong đợi preflight, nhưng trình duyệt có quyền gửi một cái.
• Gửi Access-Control-Allow-Private-Network: true nếu bạn ở địa chỉ riêng. Hiện Chrome không thực thi điều này, vì nó dựa vào một hộp thoại xin quyền người dùng một lần thay thế, nhưng việc thực thi đã bị hoãn trước đây và header này không tốn gì.

CORS

Header CORS là bắt buộc nếu bạn khai báo canAnalyseAudio, và được khuyến nghị dù bạn có khai báo hay không. Một phần tử <video> hoặc <audio> thường phát được media khác origin mà không cần chúng, và đó là điều Stage làm với một provider không khai báo khả năng này. Khai báo nó là điều thay đổi việc đó, vì Stage khi đó yêu cầu media ở một chế độ sẽ hỏng hoàn toàn nếu thiếu chúng. Xem Khả năng (capabilities) để biết vì sao, và điều gì sẽ hỏng.

Khi gửi chúng, hãy gửi trên mọi phản hồi thành công cho một yêu cầu tới địa chỉ media, cả 200 lẫn 206, và cả 416 nữa. Chúng không cần có trên 403 hay 404:

• Access-Control-Allow-Origin nêu origin đã yêu cầu (lấy từ header Origin), hoặc *. Stage không gửi thông tin xác thực, nên dùng ký tự đại diện là chấp nhận được. Nếu bạn phản chiếu origin, hãy gửi thêm Vary: Origin.
• Access-Control-Expose-Headers: Content-Length, Content-Range.
• Access-Control-Allow-Methods: GET, HEAD, OPTIONS và Access-Control-Allow-Headers: Range trong câu trả lời OPTIONS.

Nếu địa chỉ chuyển hướng, mọi bước chuyển hướng đều phải làm như vậy.

Media token

Media token là của bạn. Chúng tôi lưu nó, đã mã hóa, và đặt nó vào địa chỉ mà Stage được cấp, đó là cách Stage chứng minh với bạn rằng màn hình được phép hỏi. Nó ngăn bất kỳ ai khác trong cùng mạng duyệt qua thư viện của bạn bằng cách đoán id, điều mà trên wifi dùng chung hay wifi khách là mối lo thật chứ không phải lý thuyết.

Đổi nó, chẳng hạn mỗi lần khởi động lại, là được, vì lần đồng bộ kế tiếp báo cho chúng tôi giá trị mới. Hệ quả là một Stage đang giữ địa chỉ của bài đang phát sẽ nhận 403 ở yêu cầu range kế tiếp, nên một lần khởi động lại làm gián đoạn thứ đang trên màn hình, và một bài bắt đầu trước khi lần đồng bộ đầu tiên sau khi khởi động lại được ghi nhận cũng vậy. Hãy gửi lần đồng bộ đó sớm nhất có thể. Các bài được xác định sau đó dùng token mới và phát bình thường.

Người ta thấy gì khi nó hỏng

Có hai kiểu hỏng khác nhau, và cả phòng thấy chúng khác nhau.

Nếu dịch vụ không có địa chỉ nào để đưa cho một track, vì thư viện đã bị xóa hoặc chưa bao giờ đồng bộ, Stage báo rằng thư viện chứa bài đó không liên lạc được, và chờ. Nó không bỏ qua, vì lặng lẽ lướt hết hàng chờ sẽ che mất nguyên nhân.

Nếu dịch vụ đưa một địa chỉ và rồi trình duyệt không tải được, phần tử media báo lỗi và Stage bỏ qua bài đó và chuyển sang bài kế tiếp, không có gì trên màn hình cho biết lý do. Một quyền bị từ chối, một máy tính đang ngủ, một mạng khác, một chứng chỉ mà trình duyệt không tin, một token sai, và một tệp mà trình duyệt không giải mã được, tất cả trông hệt nhau từ phía cả phòng: các bài bắt đầu, rồi biến mất. Đó là một lý do để trả lời token sai bằng một 403 đơn giản và không gì thêm. Nó giúp tách các trường hợp khi bạn đọc nhật ký của chính mình.

Định dạng

Stage phát qua một phần tử media của trình duyệt, nên thứ phát được là thứ trình duyệt mở được. MP4/H.264, WebM và MOV chạy trực tiếp. MKV, AVI, WMV và FLV thì không, và CDG+MP3 cũng không — và CDG nói riêng là định dạng đĩa karaoke thật, phổ biến trong các thư viện thực tế.

Container mới chỉ là một nửa. Trình duyệt chỉ mở một tệp nếu nó cũng giải mã được thứ bên trong:

• MP4 và MOV phát được ở mọi nơi với video H.264 và âm thanh AAC. HEVC (H.265) phát được trên một số thiết bị và không phát được trên số khác. Một tệp .mov từ máy quay hay phần mềm dựng thường là một trong số đó.
• WebM nghĩa là video VP8 hoặc VP9 với âm thanh Vorbis hoặc Opus.
• Âm thanh MP3, và AAC trong M4A, phát được ở mọi nơi. Apple Lossless trong M4A không phát được trên mọi trình duyệt.

Không có gì trong dịch vụ nhìn vào bên trong một tệp. Bridge chỉ quyết định theo phần đuôi tệp, nên một .mp4 mà nó báo là phát được vẫn có thể bị từ chối trên một chiếc tivi cụ thể. Một tệp có phát được hay không là nhận định của bạn, và bạn là người ở vị trí để đưa ra nó.

Nếu nguồn của bạn có tệp mà trình duyệt không mở được, hãy chuyển mã (transcode). Cho đến khi làm được, hãy báo từng track bằng playable: false trên bất cứ thứ gì trình duyệt không mở được.

Một track được đánh dấu như vậy vẫn được ghi vào danh mục, và chủ của nó vẫn thấy nó trên trang thư viện, được đánh dấu là không phát được. Nó được giữ ngoài phần duyệt và tìm kiếm, để không ai xếp nó vào hàng chờ rồi nhìn nó hỏng trên tường. Cách đó tốt hơn cả hai lựa chọn còn lại: đưa nó ra rồi hỏng trước mặt cả phòng, hoặc lặng lẽ bỏ nó đi và để ai đó tự hỏi nửa bộ sưu tập của mình đâu mất.

Bỏ trống cờ này nghĩa là phát được. Một provider viết trước khi có cờ này được tin theo lời nó, thay vì bị nghi ngờ dựa trên một tên tệp mà chúng tôi chưa bao giờ được thấy.