VL Group

Rhymba v3.6 Documentation

Status Codes & Domains

Content in Rhymba has two important fields associated with it at the Geo level: status codes and domain sums. We covered some of the status codes in the Albums(), Artists(), and Media() collection documentation, but there are oh so many more. And domain sums are important if you're offering a multi-use service, e.g. a streaming AND download store. Here's the deets.

Domains: How You Can Use Content

The Rhymba API system enforces usage rules based on a bitmask of usage rights. We call these "domains" (for some legacy reasons that are too lengthy to explain here). Their values are all powers of 2 — 1, 2, 4, 8, etc. — and as such can add up to unique domain sums. Using bitwise operators, you can quickly see if a piece of content has availability for a specific usage.

Example

Say a piece of content has a domain sum of 28. There are only three domain values that can possibly add up to that domain sum:

4 + 8 + 16 = 28. No other combination of domain values adds up to 28.

Domain Values

The following table contains VL Group’s domain values & a description of each one, along with whether or not it is in current usage. Please note many domain values are currently unused and/or deprecated, but remain here for data compatibility purposes.

Status ID Status Text Description
1 Ringtone Content may be sold for use as a ringtone
2 Download Content is available for a free download. (Deprecated)
4 Podcast This content may be used in a podcast.
8 Stream This content may be used in a DMCA-compliant compulsory stream.
16 PaidDownload Content is available for paid digital download.
32 AlbumOnly Content may only be used as part of an album (Deprecated in favor of album-only status; see table below.)
64 HttpStream This content may be streamed over HTTP (Deprecated)
128 Stream_noncompulsory This content may be used in a non-compulsory stream by your system/application.

Can I Query by Domains?

Short answer: Somewhat.

Long answer: You could technically do an equality comparison, like domainsum eq 16, but this wouldn't necessarily give you back all tracks that you're whitelisted for that allow for paid downloads. Here's why.

As a part of returning results to you, we take the rights granted to us for a piece of content by the content providers and overlay your specific system or application's agreement with us. So, given that a piece of content might have been given to us by the provider for use as a paid download, compulsory stream, non-compulsory stream, and, say, podcast — resulting in a domainsum of 154 — your system or application may only be approved with this particular provider for paid downloads & compulsory stream — resulting in a customized domainsum returned to you of 24. So, in our simple example, you'd have to query for both tracks with both 16 and 24 domainsum values, and for more complex systems you'll have to query for every potential combination of domains whitelisted for your system/application.

This would certainly be easier if you could simply have a filter like domainsum & 16 gt 0, doing a bitwise AND, wouldn't it? Well, here's why that wont work: the domain values for the content you're getting back are calculated after the search lookup completes. Basically, we look up the content your system/application is whitelisted for that matches you various filters and keywords and pagination and all that, and after that we overlay the domain rights right before the content is returned to you.

Does this actually affect you, though? The good news is, likely not. Most of our API customers are doing a single type of implementation, be that downloads or streaming, and not mixed-delivery products. However, if you are doing a mixed-delivery implemention, you'll need to handle the UX of how content may be used based on the domainsum returned from Rhymba (such as hiding purchase buttons and the like). You'd have to do this for statuses like AlbumOnly described below, anyway, so just be aware of this.

Status Codes: How Are You Today, Guv'nah?

In Rhymba, status codes indicate the current state of the content. Statuses can be things like "Active" (able to be purchased) or "Takedown" (the content provider issued a takedown for the content), or even "AlbumOnly" (this track can only be sold as a part of an album). We whitelist specific status codes for your system so you shouldn't be seeing content you can't act upon in most cases; sometimes, however, a system/application may be permitted to see pre-release content, for example, and you need to be sure that your UI and user experience reflects the current status of said content.

Here's a table of the myriad of status codes you may (rarely) encounter beyond the basics. But, as mentioned: you'll only see content that's in a status you're permitted to see, so for the majority of our API customers that means you'll only ever receive results from the Rhymba Search API that are active and available for purchase or stream. So you don't really need to concern yourself with all of the entries in this massive list.

Status ID Status Text Description
0 No Status Set The content has no specific status set in our system.
1 Explicit Lyrics This content was incorrectly marked as non-explicit when it's in fact explicit.
2 Copyright Infringement The content was taken down for copyright infringement.
5 Take Down This content was taken down for various reasons.
6 Pending This content is pending some work on our side before it goes live.
7 Active This content is active & available. For tracks, that means this track may be sold as a part of an album or as an individual track.
9 Future Release This content will eventually be live.
10 Missing The audio file or other asset for this content is missing, and will likely be unable to be delivered.
11 ActiveAlternateAlbum This album is active as a replacement for another album. You should ideally never see this status.
12 BonusTrack This track is available as a "bonus" track as a part of an album sale.
13 IncompleteInformation We are missing some metadata for this content.
17 No Length Specified The content provider has not given us length information for this content, and we have yet to analyze it via our encoders — as such we generally don't make it available.
18 AlbumOnly This content is only permitted to be sold as a whole album by album ID. If a track is in this status, you should not attempt to purchase it as an individual track (even if you're also purchasing all of the other tracks on the album); you should only attempt purchase by album ID. If an album is in this status, you should only purchase it by album ID, not by its component media IDs.
20 TrackOnly This content is only permitted to be sold as individual tracks, not by album ID. If a track is in this status, you should not attempt to purchase it as part of an album using an album ID; you should only attempt purchase it by its media ID. If an album is in this status, you should not attempt to purchase it by album ID, only by its component media IDs. We know this is odd. It's something the content providers do from time to time.
21 PartialAlbumOnly One or more tracks on an album are only available if the album is purchased as a whole.
105 PendingTakeDown This content is going to be taken down soon.
107 PendingActive This content will be going active in our next database update.
109 PendingFutureRelease This content will be marked as a future release in an upcoming database update.
118 PendingAlbumOnly This content will be going active in an upcoming database update, and will be marked as album only. See above for description of that status.
120 PendingTrackOnly This content will be going active in an upcoming database update, and will be marked as track only. See above for description of that status.
121 PendingPartialAlbum This content will be going active in an upcoming database update, and will be marked as partial album only. See above for description of that status.
207 Price Pending - Active This content is active, but we don't have a valid price point for it. You will likely not see content in this status if your access grants you purchase capability.
218 Price Pending - AlbumOnly This content is active as album only, but we don't have a valid price point for it. You will likely not see content in this status if your access grants you purchase capability.
1007 ActiveFutureRelease This helper status is for scenarios where we need content to be active for a specific customer, but having it be future release for others.
1011 AlternateAlbumFutureRelease This helper status is for scenarios an album will be an alternate release in the future.
1018 AlbumOnlyFutureRelease This content will be coming out at some point in the future, and will be album only.
1020 TrackOnlyFutureRelease This content will be coming out at some point in the future, and will be track-only.
1021 PartialAlbumFutureRelease This content will be coming out at some point in the future, but is only a partial album.
1022 PendingUpload This is an Audio Publisher status, meaning the files for the content have not yet been uploaded by the client.
1024 PendingPublish This is an Audio Publisher status, meaning the files for the content have been uploaded & processed, but the content has yet to be published for active use.
1035 Deleted / Inactive This content has been completely deleted from our system, for various reasons.
1036 PendingScan This is an Audio Publisher and encoder status, meaning the files for the content have been uploaded, but are awaiting information scan by our encoders.
1037 PendingActivation This content is awaiting activation, either via Audio Publisher or another piece of our infrastructure.
1038 PendingTranscode This content is about to be converted from a source file to another through the Audio Publisher process.
1041 International Content is not available in the US at all, or another territory-based exception has occurred.
1207 Price Pending - Active Future Release This content will be active at some point in the future, but we don't have a valid price point for it. You will likely not see content in this status.
1218 Price Pending - AlbumOnly Future Release This content will be active & album-only at some point in the future, but we don't have a valid price point for it. You will likely not see content in this status.
3007 INTL-ActiveRelease This content is available but we've flagged it as international, meaning it's likely not available in the U.S. Most API customers will not see content in this status.
3011 INTL-AlternateAlbumRelease This content is available as an alternate album, but we've flagged it as international, meaning it's likely not available in the U.S. Most API customers will not see content in this status.
3018 INTL-AlbumOnlyRelease This content is available as album-only but we've flagged it as international, meaning it's likely not available in the U.S. Most API customers will not see content in this status.
3020 INTL-TrackOnlyFutureRelease This content will be available as track-only in the future, but we've flagged it as international, meaning it's likely not available in the U.S. Most API customers will not see content in this status.
3021 INTL-PartialAlbumRelease This content is a partial album but we've flagged it as international, meaning it's likely not available in the U.S. Most API customers will not see content in this status.