lets.dj

Gửi danh mục

Đây là bản dịch. Bản tiếng Anh là bản có giá trị: nếu hai bản khác nhau, hãy làm theo bản tiếng Anh. Bản dịch chỉ được cung cấp để tiện theo dõi. Đọc trang này bằng tiếng Anh

Đẩy một danh mục

Gửi sync token dưới dạng bearer token:

POST https://api.lets.dj/providers/sync
Authorization: Bearer <sync token>
Content-Type: application/json

{
  "baseUrl": "https://0123456789abcdef.letsdj.io:8443",
  "mediaToken": "<secret you generate>",
  "capabilities": {
    "canTransposeKey": false,
    "canSeek": true,
    "allowsSharing": true,
    "allowsCommercialUse": false
  },
  "tracks": [
    {
      "externalId": "5ec27f0af401a3ab",
      "title": "Diễm Xưa",
      "artist": "Trịnh Công Sơn",
      "durationSeconds": 254,
      "thumbnailUrl": "https://...",
      "playable": true
    }
  ],
  "final": true
}

baseUrl là bắt buộc và phải là https. Stage là một trang HTTPS và sẽ từ chối tải media qua HTTP thường, nên điều này bị từ chối ngay lúc đồng bộ thay vì thất bại âm thầm trên màn hình về sau. Chỉ phần origin của nó được dùng để dựng địa chỉ media, như mô tả trong Phát nội dung media, và chứng chỉ đứng sau nó phải là chứng chỉ mà trình duyệt đã tin cậy sẵn.

mediaToken là bắt buộc, và do bạn tạo ra, không phải chúng tôi. Bạn là người phải thực thi nó, nên bạn cũng nên là người sở hữu nó. Hãy dùng một giá trị không đoán được và an toàn khi đặt trong query string; hex ngẫu nhiên hoặc base64url từ 128 bit trở lên là đủ. Đổi nó mỗi lần khởi động lại là được, với hệ quả được mô tả trong Phát nội dung media.

capabilities nói bạn là gì và sẽ làm gì. Xem Khả năng (capabilities). Nó được thay thế toàn bộ sau mỗi lần đồng bộ, nên hãy gửi đầy đủ mỗi lần. Một cờ bạn bỏ đi sẽ trở về giá trị mặc định, và các giá trị mặc định không phải tất cả đều là false.

limits và consoleUrl được mô tả trong Trả lời theo yêu cầu. Chúng cũng được thay thế toàn bộ: một lần đồng bộ bỏ consoleUrl sẽ gỡ liên kết tới console của bạn.

tracks là bắt buộc và có thể rỗng. Gửi tối đa 500 track mỗi yêu cầu; nhiều hơn là 400.

final là tùy chọn, và mặc định của nó là true. Xem Thay thế, và bổ sung.

Track

  • externalId là bắt buộc. Nó là của bạn, một chuỗi không rỗng bất kỳ, và duy nhất trong thư viện của bạn. Nó cũng đặt tên cho media của track: nó là phần cuối của địa chỉ media, được mã hóa phần trăm.
  • title là bắt buộc.
  • artist, durationSeconds (tính bằng giây, một số hữu hạn bất kỳ) và thumbnailUrl là tùy chọn.
  • playable là tùy chọn. Chỉ giá trị false nguyên văn mới có ý nghĩa. Xem Định dạng.

externalId phải ổn định qua các lần quét lại. Một bài đã xếp hàng được tìm lại qua nó, nên một id sinh ra từ trạng thái thay đổi được sẽ làm hỏng các bài hát giữa chừng buổi tiệc. Bridge sinh id từ kích thước tệp và các byte ở hai đầu tệp, không phải từ đường dẫn, để việc di chuyển hay đổi tên một tệp không làm mồ côi những chỉnh sửa người ta đã làm cho nó.

Một track không có externalId hoặc không có title thì không thể được tìm thấy hay phát, và bị bỏ qua mà không làm hỏng cả lô. Phản hồi cho biết có bao nhiêu track được giữ lại, nên hãy so với số bạn đã gửi.

Thay thế, và bổ sung

Một lần đồng bộ làm một trong hai việc, và final là thứ chọn.

Thay thế danh mục. Gửi nó thành các lô tối đa 500, với final: false trên mọi lô trừ lô cuối. Lô cuối xóa mọi track mà không lô nào trong lần thay thế đó nhắc đến. Một chỉnh sửa mà chủ thư viện đã làm vẫn còn sau khi xóa, và trở lại nếu track trở lại. Một track đang chờ được tải về không bao giờ bị xóa theo cách này: xem Trả lời theo yêu cầu.

Bổ sung hoặc cập nhật. Gửi final: false, và không có gì bị xóa. Đây là cách báo một track đã tải về, và cách một provider biết chính xác điều gì thay đổi có thể chỉ nói riêng điều đó.

Vì final mặc định là true, một lần đồng bộ bỏ trống nó là một lần thay thế. Một track đơn lẻ gửi theo cách đó sẽ xóa phần còn lại của danh mục. Một lô rỗng với final: true xóa tất cả. Vì vậy khi một lần quét thất bại, ví dụ vì ổ đĩa bị rút ra hoặc ổ chia sẻ đang ngủ, đừng gửi những gì lần quét hỏng tìm được. Hãy để nguyên danh mục lần trước và báo cho người dùng, đó là điều bridge làm.

Câu trả lời

{ "ok": true, "accepted": 312, "trackCount": 812 }

accepted là số track của yêu cầu này được giữ lại. trackCount là số track thư viện đang có sau đó. Thư viện trở nên sẵn sàng lần đầu tiên một lần đồng bộ được ghi nhận.

  • 400 kèm một error nói rõ lý do: body must be JSON, baseUrl is required, baseUrl must be https, consoleUrl must be https, tracks must be an array, at most 500 tracks per batch, hoặc mediaToken is required.
  • 401 và 403 như mô tả trong Quy ước.
  • 503 nghĩa là dịch vụ chưa lưu được một bí mật vào lúc này. Lỗi từ phía chúng tôi, đáng thử lại sau.

Ảnh bìa

Tùy chọn, và được xếp lớp giống cách một chỉnh sửa được xếp lớp: thứ chúng tôi đang giữ luôn thắng, nhưng ở đây không có gì từng chạm vào tệp bên phía bạn.

Hai cách để cung cấp:

Một URL, trong nội dung đồng bộ: thumbnailUrl trên mỗi track, như ví dụ ở trên. Bất cứ thứ gì trình duyệt trên điện thoại của khách lấy được đều dùng được. Đây là lựa chọn sai nếu URL chỉ phân giải được trong mạng của bạn hoặc hết hạn sau vài giờ; hãy dùng endpoint bên dưới.

Các byte, đẩy tới một endpoint riêng. Đây là con đường một provider trong mạng riêng buộc phải đi, vì nó không thể đưa ra một URL mà ai khác tới được:

POST https://api.lets.dj/providers/art?externalId=<externalId>
Authorization: Bearer <sync token>
Content-Type: image/jpeg

<raw image bytes>

externalId phải khớp một track đã được báo qua /providers/sync, nên hãy đẩy danh mục trước và ảnh bìa sau. Một track mà dịch vụ chưa biết là 404 với unknown track. Content-Type phải bắt đầu bằng image/, và nội dung không được rỗng. Hãy gửi JPEG, PNG hoặc WebP: thứ gì trình duyệt không vẽ được sẽ được lưu và hiện như một hình hỏng.

Giới hạn là 1 MB, tức 1.048.576 byte. Chúng tôi không giải mã hay đổi kích thước thứ bạn gửi, nên một hình quá lớn bị 400 thẳng thừng thay vì bị lấy mẫu lại âm thầm. Hãy gửi thứ đã có kích thước phù hợp cho ảnh thu nhỏ. Một ảnh JPEG 1280×720 nặng 70 KB, loại mà điện thoại hay một bản rip DVD vốn đã tạo ra, nằm dưới giới hạn rất xa.

Đẩy lại ảnh bìa cho một track sẽ thay thế hình trước đó. Ảnh bìa vẫn còn qua các lần đồng bộ sau của cùng track, và bị xóa cùng track khi một lần thay thế loại nó đi.

Ảnh bìa đẩy theo cách này thắng một thumbnailUrl của cùng track, vì các byte chúng tôi đã giữ thắng một liên kết có thể cũ đi hay 404 về sau. Cả hai đều thua một chỉnh sửa làm trong ứng dụng: danh mục của bạn là một nguồn, không phải tiếng nói cuối cùng.

Chủ thư viện có thể thay đổi gì

Chủ thư viện có thể sửa tên bài, nghệ sĩ và hình của một track trong ứng dụng. Một chỉnh sửa thắng bất cứ thứ gì bạn gửi, theo từng trường, và nó còn nguyên qua mọi lần đồng bộ sau, vì nó được lưu tách khỏi danh mục và gắn với externalId. Bạn không bao giờ được báo về một chỉnh sửa. Đó là lý do một externalId ổn định quan trọng hai lần: một track đổi id là một track khác, và bắt đầu lại mà không có chúng.