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.
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:
- Podcast, with a domain value of 4.
- Stream, with a domain value of 8.
- And PaidDownload, with a domain value of 16.
4 + 8 + 16 = 28. No other combination of domain values adds up to 28.
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.|