From 94ceff572d0a92e290593228800395fa17db7568 Mon Sep 17 00:00:00 2001 From: Sam Gutentag <1404219+samgutentag@users.noreply.github.com> Date: Wed, 3 Apr 2024 15:50:37 -0700 Subject: [PATCH 01/12] initial commit --- docs/.vscode/spellright.dict | 4 + .../distributors/introduction/overview.mdx | 40 +++ .../distributors/run-a-server/overview.mdx | 16 + .../run-a-server/run-a-ddex-server.mdx | 24 ++ docs/docs/distributors/specification/ern3.mdx | 306 +++++++++++++++++ .../distributors/specification/overview.mdx | 316 ++++++++++++++++++ docs/docusaurus.config.js | 5 + docs/sidebars.js | 24 ++ 8 files changed, 735 insertions(+) create mode 100644 docs/docs/distributors/introduction/overview.mdx create mode 100644 docs/docs/distributors/run-a-server/overview.mdx create mode 100644 docs/docs/distributors/run-a-server/run-a-ddex-server.mdx create mode 100644 docs/docs/distributors/specification/ern3.mdx create mode 100644 docs/docs/distributors/specification/overview.mdx diff --git a/docs/.vscode/spellright.dict b/docs/.vscode/spellright.dict index f285211ebfd..c43da3e57cb 100644 --- a/docs/.vscode/spellright.dict +++ b/docs/.vscode/spellright.dict @@ -2,10 +2,13 @@ abi audius blockhash ciphertexts +ddex delegater delegaters docusaurus erc +ern3 +ern4 esque eth ethereum @@ -24,6 +27,7 @@ jwt mainnet metamask multisig +nft nodejs nonpayable npm diff --git a/docs/docs/distributors/introduction/overview.mdx b/docs/docs/distributors/introduction/overview.mdx new file mode 100644 index 00000000000..c784e585de2 --- /dev/null +++ b/docs/docs/distributors/introduction/overview.mdx @@ -0,0 +1,40 @@ +--- +id: overview +title: DDEX with Audius +pagination_label: DDEX with Audius +sidebar_label: DDEX with Audius +description: Audius Protocol Documentation +--- + +import useBaseUrl from '@docusaurus/useBaseUrl' + +:::tip Looking for how to accept uploads from your distributor? + +Visit [ddex.audius.co](https://ddex.audius.co) and check the +[Audius Support Page](https://support.audius.co) for more information. + +::: + +## What is DDEX + +Digital Data Exchange (or "DDEX") is an international standards-setting organization that was formed +in 2006 to develop standards that enable companies to communicate information along the digital +supply chain more efficiently by: + +- Developing standard message and file formats (XML or flat-file) +- Developing choreographies for specific business transactions +- Developing communication protocols (SFTP or based on web services) +- Working with industry bodies to create a more efficient supply chain. + +### More Information + +- Learn more on the official DDEX Website here: [https://ddex.net/](https://ddex.net/) +- Looking for a deeper technical dive? Checkout the DDEX knowledge base here: + [https://kb.ddex.net/](https://kb.ddex.net/) + +--- + +## Open Source + +Like many Audius projects, all of the code is open source and available on +[GitHub](https://github.com/AudiusProject/ddex) diff --git a/docs/docs/distributors/run-a-server/overview.mdx b/docs/docs/distributors/run-a-server/overview.mdx new file mode 100644 index 00000000000..450aebbfc19 --- /dev/null +++ b/docs/docs/distributors/run-a-server/overview.mdx @@ -0,0 +1,16 @@ +--- +id: overview +title: Overview +pagination_label: Overview +sidebar_label: Overview +description: Audius Protocol Documentation +unlisted: true +--- + +import useBaseUrl from '@docusaurus/useBaseUrl' + +:::info Coming Soon! + +Still working on this one, but check back soon for updates on how to run our own DDEX Server. + +::: diff --git a/docs/docs/distributors/run-a-server/run-a-ddex-server.mdx b/docs/docs/distributors/run-a-server/run-a-ddex-server.mdx new file mode 100644 index 00000000000..1e2f4ee4039 --- /dev/null +++ b/docs/docs/distributors/run-a-server/run-a-ddex-server.mdx @@ -0,0 +1,24 @@ +--- +id: run-a-ddex-server +title: Running a Server +pagination_label: Running a Server +sidebar_label: Running a Server +description: Audius Protocol Documentation +draft: true +--- + +import useBaseUrl from '@docusaurus/useBaseUrl' + +:::info Coming Soon! + +Still working on this one, but check back soon for updates on how to run our own DDEX Server. + +::: + +## Instructions + +- Go to audius-docker-compose + - Should this be audius-d? +- Run install script +- Set env vars + - Go to [DDEX README](https://github.com/AudiusProject/ddex) in audius-protocol and diff --git a/docs/docs/distributors/specification/ern3.mdx b/docs/docs/distributors/specification/ern3.mdx new file mode 100644 index 00000000000..bcfec3e7878 --- /dev/null +++ b/docs/docs/distributors/specification/ern3.mdx @@ -0,0 +1,306 @@ +--- +id: ern3 +title: ERN3 +pagination_label: ERN3 +sidebar_label: ERN3 +description: Audius Protocol Documentation +--- + +import useBaseUrl from '@docusaurus/useBaseUrl' + +## General Guidance + +- Audius only accepts price information using absolute prices (e.g. via `WholesalePricePerUnit`). + Price codes will be ignored (e.g. `PriceType`). +- Audius also does not support `ValidityPeriod` `EndDate`s. This includes using `EndDate` to specify + multiple `ValidityPeriod`s with different prices. We can only parse 1 `ValidityPeriod` + `StartDate`. +- Audius only accepts the `Worldwide` `TerritoryCode`. +- `NonInteractiveStream` is not supported. +- A `ReleaseDeal` is required with a `DealReleaseReference` to each track on an album. +- A `ReleaseDeal` is not required with a `DealReleaseReference` to an album release. If an album + deal is not specified, the album defaults to being free to stream, but each of its tracks is + configured according to the track’s `ReleaseDeal` `DealTerms`. + +--- + +## Albums + + + +Audius accepts the following DDEX `Deal`s for **album** releases (details are the same as the corr. +deals in the tracks section below): + +1. Stream for free (not downloadable) +2. Stream gated by premium/USDC (artist-defined payment amount) (not downloadable) + +--- + +## Tracks + +Audius accepts the following DDEX `Deal`s for **track** releases: + +### Stream for free (not downloadable) + +1. `CommercialModelType`: `FreeOfChargeModel` +2. `UseType`: `Stream` or `OnDemandStream` +3. `PriceType`: not supported +4. `WholesalePricePerUnit`: N/A +5. `ValidityPeriod` + 1. `StartDate`: any +6. `TerritoryCode`: `Worldwide` + +```xml + + + FreeOfChargeModel + + OnDemandStream + + Worldwide + + 2023-09-02 + + + +``` + +### Stream gated by premium/USDC (artist-defined payment amount) (not downloadable) + +1. `CommercialModelType`: `PayAsYouGoModel` +2. `UseType`: `Stream` or `OnDemandStream` +3. `PriceType`: not supported +4. `WholesalePricePerUnit`: any nonzero USD amount +5. `ValidityPeriod` + 1. `StartDate`: any +6. `TerritoryCode`: `Worldwide` + +```xml + + + PayAsYouGoModel + + OnDemandStream + + Worldwide + + 1.0 + ... + + + 2023-09-02 + + + +``` + +### Stream gated by NFT (not downloadable) + +1. `CommercialModelType`: `UserDefined` (`NFTGated`) +2. `UseType`: `Stream` or `OnDemandStream` +3. `PriceType`: not supported +4. `WholesalePricePerUnit`: N/A +5. `ValidityPeriod` + 1. `StartDate`: any +6. `TerritoryCode`: `Worldwide` +7. `Conditions` (custom XML specific to Audius) + + 1. For Ethereum NFTs: + + ```xml + + eth +
// The Ethereum address of the NFT contract + // The standard followed by the NFT - either "ERC-721" or "ERC-1155" + // The name of the NFT + // The slug of the NFT collection. E.g. if your collection is located at https://opensea.io/collection/example-nft, the slug is "example-nft". + // Optional: URL to the image representing the NFT + // Optional: URL to an external resource providing more details about the NFT + + ``` + + ii. For Solana NFTs: + + ```xml + + sol +
// The address of the NFT on the Solana blockchain + // The name of the NFT + // Optional: URL to the image representing the NFT + // Optional: URL to an external resource providing more details about the NFT + + ``` + +```xml + + + UserDefined + + OnDemandStream + + Worldwide + + 2023-09-02 + + + eth +
0xAbCdEfGhIjKlMnOpQrStUvWxYz
+ ERC-721 + Example NFT + example-nft + https://www.example.com/nft-image.png + https://www.example.com/nft-details + + + +``` + +### Stream gated by follow (not downloadable) + +1. `CommercialModelType`: `UserDefined` (`FollowGated`) +2. `UseType`: `Stream` or `OnDemandStream` +3. `PriceType`: not supported +4. `WholesalePricePerUnit`: N/A +5. `ValidityPeriod` + 1. `StartDate`: any +6. `TerritoryCode`: `Worldwide` + +```xml + + + UserDefined + + OnDemandStream + + Worldwide + + 2023-09-02 + + + +``` + +### Stream gated by tip (not downloadable) + +1. `CommercialModelType`: `UserDefined` (`TipGated`) +2. `UseType`: `Stream` or `OnDemandStream` +3. `PriceType`: not supported +4. `WholesalePricePerUnit`: N/A +5. `ValidityPeriod` + 1. `StartDate`: any +6. `TerritoryCode`: `Worldwide` + +```xml + + + UserDefined + + OnDemandStream + + Worldwide + + 2023-09-02 + + + +``` + +### Download for free + +:::info Downloadable content is streamable. + +If you can download it, you can stream it. + +::: + +1. `CommercialModelType`: `FreeOfChargeModel` +2. `UseType`: `Stream` or `OnDemandStream`, `PermanentDownload` +3. `PriceType`: not supported +4. `WholesalePricePerUnit`: N/A +5. `ValidityPeriod` + 1. `StartDate`: any +6. `TerritoryCode`: `Worldwide` + +```xml + + + FreeOfChargeModel + + OnDemandStream + PermanentDownload + + Worldwide + + 2023-09-02 + + + +``` + +### Download gated by premium/USDC (artist defined payment amount) + +:::info Downloadable content is streamable. + +If you can download it, you can stream it. + +::: + +1. `CommercialModelType`: `PayAsYouGoModel` +2. `UseType`: `Stream` or `OnDemandStream`, `PermanentDownload` +3. `PriceType`: not supported +4. `WholesalePricePerUnit`: any USD amount +5. `ValidityPeriod` + 1. `StartDate`: any +6. `TerritoryCode`: `Worldwide` + +```xml + + + PayAsYouGoModel + + OnDemandStream + PermanentDownload + + Worldwide + + 1.0 + ... + + + 2023-09-02 + + + +``` + +### Download gated by follow + +:::info Downloadable content is streamable. + +If you can download it, you can stream it. + +::: + +1. `CommercialModelType`: `UserDefined` (`FollowGated`) +2. `UseType`: `Stream` or `OnDemandStream`, `PermanentDownload` +3. `PriceType`: not supported +4. `WholesalePricePerUnit`: N/A +5. `ValidityPeriod` + 1. `StartDate`: any +6. `TerritoryCode`: `Worldwide` + +```xml + + + UserDefined + + OnDemandStream + PermanentDownload + + Worldwide + + 2023-09-02 + + + +``` diff --git a/docs/docs/distributors/specification/overview.mdx b/docs/docs/distributors/specification/overview.mdx new file mode 100644 index 00000000000..e56a4aa17a9 --- /dev/null +++ b/docs/docs/distributors/specification/overview.mdx @@ -0,0 +1,316 @@ +--- +id: overview +title: DDEX Specification +pagination_label: DDEX Specification +sidebar_label: DDEX Specification +description: Audius Protocol Documentation +draft: true +--- + +import useBaseUrl from '@docusaurus/useBaseUrl' + +## Schema + +### Mapping Audius metadata to DDEX fields + +This depends on the ERN version. Mapping for our Sony example (ERN 3.81): + +:::note Each Release has multiple `ReleaseDetailsByTerritory` elements + +Audius only uses the one with `Worldwide`. Similarly, for each +`SoundRecording` we only use the `SoundRecordingDetailsByTerritory` where TerritoryCode is +Worldwide. + +::: + +| Audius | DDEX | Notes | +| ------------------------------------------------------------------ | ----------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| releaseDate | /ReleaseList/Release/GlobalOriginalReleaseDate | TODO: This is apparently deprecated. Probably needs to change to use a date from DealList | +| duration | /ResourceList/SoundRecording/Duration | Parsed as ISO 8601. Falls back to /ReleaseList/Release/Duration from the release with a matching ResourceReference | +| title | | +| artist | | +| preview | | +| isrc | | +| genre | | | +| | | We don't have the concept of "Disks" which some albums have multiple of. For now disks are flattened into the same album with no differentiation. See | +| description | | There was some element I remember being similar to description, but in the Sony example I didn’t see any actual description. | +| iswc | | | +| license | | | +| previewStartSeconds | | DDEX supports preview duration, but Audius sets it to exactly 30 seconds. | +| isUnlisted | | Probably parse from DealList. See https://kb.ddex.net/implementing-each-standard/best-practices-for-all-ddex-standards/deals-and-commercial-aspects/availability-and-visibility/ | +| fieldVisibility.\* (moods, tags, genre, share, playCount, remixes) | | Probably parse from DealList. See https://kb.ddex.net/implementing-each-standard/best-practices-for-all-ddex-standards/deals-and-commercial-aspects/availability-and-visibility/ | +| remixOf | | Possible equivalent in DDEX RelatedResource. See https://kb.ddex.net/implementing-each-standard/best-practices-for-all-ddex-standards/guidance-on-releaseresourcework-metadata/linking-different-releases-and-resources/ and https://kb.ddex.net/implementing-each-standard/best-practices-for-all-ddex-standards/guidance-on-contributors,-artists-and-writers/communicating-remixes-and-remixers/ | +| origFilename | | Possible equivalent in DDEX | +| isOriginalAvailable | | Possible equivalent in DDEX | +| origFileCid | | Possible equivalent in DDEX | +| streamConditions | | Possible equivalent in DealList in the future | +| isStreamGated | | Possible equivalent in DealList in the future | +| isDownloadGated | | Possible equivalent in DealList in the future | +| downloadConditions | | Possible equivalent in DealList in the future | +| download.cid | | Possible equivalent in DealList in the future | +| download.isDownloadable | | Possible equivalent in DealList in the future | +| download.requiresFollow | | Possible equivalent in DealList in the future | +| mood | | No equivalent in DDEX | +| tags | | No equivalent in DDEX | +| aiAttributionUserId | | No equivalent in DDEX | +| | /ReleaseList/Release/ReleaseDetailsByTerritory[TerritoryCode="Worldwide"]/PLine | TODO: This has copyright data which we likely want to add to the track/album’s description. Although https://kb.ddex.net/implementing-each-standard/best-practices-for-all-ddex-standards/guidance-on-releaseresourcework-metadata/pline-and-cline/ says it’s not mandatory | +| | /ReleaseList/Release/ReleaseDetailsByTerritory[TerritoryCode="Worldwide"]/LabelName | | +| | other IDs (GRid, UPC, etc) | All possible options are enumerated https://kb.ddex.net/implementing-each-standard/best-practices-for-all-ddex-standards/guidance-on-identifiers-and-iso-codes-lists/communication-of-identifiers-in-ddex-messages/ | +| | ParentalWarningType | No equivalent in Audius | + +### Handling deliveries with multiple `` elements + +My understanding is that we should parse out each one and return a single album (assuming it’s +marked as an album and not random unrelated tracks). + +However, we have to also parse each `/DealList/ReleaseDeal` and set the visibility metadata of each +track based on if its the ReleaseDeal’s `DealReleaseReference` matches the track. See +[here](https://kb.ddex.net/implementing-each-standard/best-practices-for-all-ddex-standards/guidance-on-releaseresourcework-metadata/trackreleases/) +and +[here](https://kb.ddex.net/implementing-each-standard/best-practices-for-all-ddex-standards/guidance-on-releaseresourcework-metadata/release-types-for-trackreleases/). + +--- + +## Miscellaneous + +### What’s our DDEX Party Identifier (DPID)? + +Tiki Labs, Inc. has a DPID of `PA-DPIDA-202401120D-9`. According to +[this](https://ddex.net/implementation/implementation-licence-and-ddex-party-identifiers/), a DPID +is something every company accepting deliveries needs to receive by signing +[this license](https://ddex.net/implementation/implementation-licence-terms-and-conditions/). + +--- + +## Open Questions + +### How does each `` map to Audius? + +According to +[this](https://kb.ddex.net/implementing-each-standard/best-practices-for-all-ddex-standards/guidance-on-releaseresourcework-metadata/primary-and-secondary-resources/), +we **must** have one of these ``s in order to make a track visible. + +None of the existing options I’ve seen for deal types make sense for Audius: + +1. `PayAsYouGoModel`: “A CommercialModel where the Service or Product offering is financed by + revenue generated from payment (set at any level but not zero) for each Usage which the Customer + makes of the Service or Product.” +2. `SubscriptionModel`: A CommercialModel where the Service or Product offering is financed by + revenue generated from a Customer Subscription. +3. `AdvertisementSupportedModel`: `` + +UseTypes I’ve seen: + +1. `Stream` +2. `NonInteractiveStream` (radio, no fast forward or playlist / search + play on demand. skip OK) +3. `OnDemandStream` +4. `PermanentDownload` (what it sounds like - store locally is OK) +5. `ConditionalDownload` (like Spotify - as long as you’re subscribed you can download. offline + mode) + +Example Deal: + +```bash + + + AdvertisementSupportedModel + + Stream + + + 2018-01-10 + + + +``` + +Another example: + +```bash + + + PayAsYouGoModel + + PermanentDownload + + + B89 + + + 2023-09-02 + + 2023-09-02 + 2023-09-02 + 2023-09-02 + 2023-09-02 + + +``` + +Third example: + +```bash + + + SubscriptionModel + + ConditionalDownload + NonInteractiveStream + OnDemandStream + + + 2023-09-02 + + + +``` + +Fourth example: + +```bash + + + PayAsYouGoModel + + PermanentDownload + + Worldwide + + FRONT + FRONT + + + 2021-03-16 + + + +``` + +### Proposed (new) DealTypes for Audius types: + +1. Stream for free: + 1. CommercialModelType: `FreeOfChargeModel` + 2. UseType options: `Stream` + 3. PriceType options: N/A + 4. PriceRangeType options: + 5. WholeSalePricePerUnit vs retail price (label has to be paid the wholesale price, and we have + to mark it up (retail) to be able to make money): +2. Stream gated by premium/USDC (artist-defined payment amount) + 1. CommercialModelType: `PayAsYouGoModel` + 2. UseType options: `Stream` + 3. PriceType options: + 4. PriceRangeType options: + 5. WholeSalePricePerUnit vs retail price (label has to be paid the wholesale price, and we have + to mark it up (retail) to be able to make money): +3. Stream gated by NFT + 1. CommercialModelType: `UserDefined` (`NFTGated`) + 2. UseType options: `Stream` + 3. PriceType options: + 4. PriceRangeType options: + 5. WholeSalePricePerUnit vs retail price (label has to be paid the wholesale price, and we have + to mark it up (retail) to be able to make money): +4. Stream gated by follow + 1. CommercialModelType: `UserDefined` (`FollowGated`) + 2. UseType options: `Stream` + 3. PriceType options: + 4. PriceRangeType options: + 5. WholeSalePricePerUnit vs retail price (label has to be paid the wholesale price, and we have + to mark it up (retail) to be able to make money): +5. Stream gated by tip + 1. CommercialModelType: `UserDefined` (`TipGated`) or `PayAsYouGoModel`? + 2. UseType options: `Stream` + 3. PriceType options: + 4. PriceRangeType options: + 5. WholeSalePricePerUnit vs retail price (label has to be paid the wholesale price, and we have + to mark it up (retail) to be able to make money): +6. Download for free + 1. CommercialModelType: `FreeOfChargeModel` + 2. UseType options: `Stream`, `PermanentDownload` + 3. PriceType options: N/A + 4. PriceRangeType options: N/A + 5. WholeSalePricePerUnit vs retail price (label has to be paid the wholesale price, and we have + to mark it up (retail) to be able to make money): N/A +7. Download gated by premium/USDC (artist defined payment amount) + 1. CommercialModelType: `PayAsYouGoModel` + 2. UseType options: `Stream`, `PermanentDownload` + 3. PriceType options: + 4. PriceRangeType options: + 5. WholeSalePricePerUnit vs retail price (label has to be paid the wholesale price, and we have + to mark it up (retail) to be able to make money): +8. Download gated by follow + 1. CommercialModelType: `UserDefined` (`FollowGated`) + 2. UseType options: `Stream`, `PermanentDownload` + 3. PriceType options: + 4. PriceRangeType options: + 5. WholeSalePricePerUnit vs retail price (label has to be paid the wholesale price, and we have + to mark it up (retail) to be able to make money): +9. (If you can’t stream it, you can’t download it) + +### How do we parse each ID? Which ID type is the primary differentiator? + +There are different IDs that the XML can provide, like GRid, ICPN, CatalogNumber, ProprietaryId, and +more (all ID options are enumerated +[here](https://kb.ddex.net/implementing-each-standard/best-practices-for-all-ddex-standards/guidance-on-identifiers-and-iso-codes-lists/communication-of-identifiers-in-ddex-messages/)). +For now, we ignore them and only look at ISRC, which I don’t think is correct. + +Tentative decision: According to +[this](https://kb.ddex.net/implementing-each-standard/best-practices-for-all-ddex-standards/guidance-on-releaseresourcework-metadata/trackreleases/), +we might need to at least store the GRid and ProprietaryId in the DDEX db somewhere for future +reference. We should support more ID fields in our metadata to index (see Ray’s comment above). + +1. Is it acceptable to have 30 second previews when DDEX tells us exactly how long they should be? + - Context: We’re parsing out the data, but Audius is hardcoded to 30 second previews. This goes + against the variable lengths that different DDEX releases specify. +2. How do we want to support releases that have multiple artists? + - Context: According to + [this](https://kb.ddex.net/implementing-each-standard/best-practices-for-all-ddex-standards/guidance-on-contributors,-artists-and-writers/contributors,-artists-and-writers/) + and + [this](https://kb.ddex.net/implementing-each-standard/best-practices-for-all-ddex-standards/guidance-on-contributors,-artists-and-writers/information-on-displayartists,-displayartistnames,-contributors-and-indirectcontributors/), + we should use “Display Artist Name” which could actually be 2 artists like “Drake & The Weeknd” + so it wouldn’t match an account. Also, to support showing “ID” for artist and/or track for + things like music festival sets, I think we’d need to have some kind of decoupling between + display names and actual accounts. + - Tentative decision: add some more fields to index. See Ray’s comment above and + https://www.ifpi.org/wp-content/uploads/2020/08/GRid_Standard_v2_1.pdf +3. Do we need to upload an acknowledgement XML file for each delivery? + - Context: + [This](https://ernccloud.ddex.net/electronic-release-notification-message-suite-part-3%253A-choreographies-for-cloud-based-storage/5-release-by-release-profile/5.1-choreography/) + says we “shall” upload XML acknowledging exactly what was done for each release (to a separate + acknowledgements folder according to + [this](https://ernccloud.ddex.net/electronic-release-notification-message-suite-part-3%253A-choreographies-for-cloud-based-storage/5-release-by-release-profile/5.2-file-server-organisation/)). + Does Fuga require this or have any special constraints to be mindful of when uploading acks? +4. Do we need to handle separate territories? + - Context: For example, it looks like the Sony example DealList allows for downloading in some + countries but not others. +5. How should we handle all the other fields we don’t support? + - Context: See table above. The main ones are LabelName and PLineText (copyright info). Maybe we + just add the PLineText to the track/album description? +6. Our genres don’t match the genres in DDEX. For example, Sony sent a delivery with “Hip hop” while + our equivalent is “Hip-hop/Rap.” + - Context: For now, we have an explicit mapping, which will break any time there’s a new genre. + Do we want to keep on this explicit mapping path? + +## Main areas of work remaining + +- Previews: see question above - we’re parsing out preview info, but the backend is hardcoded to 30 + second previews instead of whatever variable length each release specifies +- Making metadata un-editable by artist +- Processing updates and deletes. One potential blocker on this is that we don’t have a “replacing + of audio” feature. See + [here](https://kb.ddex.net/implementing-each-standard/best-practices-for-all-ddex-standards/guidance-on-message-exchange-protocols-and-choreographies/update-indicator/) + and + [here](https://kb.ddex.net/implementing-each-standard/best-practices-for-all-ddex-standards/guidance-on-message-exchange-protocols-and-choreographies/differentiating-inserts-from-updates/) + for DDEX spec details when implementing. +- According to + [this](https://kb.ddex.net/implementing-each-standard/best-practices-for-all-ddex-standards/guidance-on-message-exchange-protocols-and-choreographies/no-resources-in-initial-delivery/), + we should allow a release to not contain all the files (ie, the first delivery only has metadata, + and a future delivery will include the actual assets). Also see + [here](https://kb.ddex.net/implementing-each-standard/best-practices-for-all-ddex-standards/guidance-on-releaseresourcework-metadata/ern-message-without-resources/) +- Maybe support + [stems](https://kb.ddex.net/implementing-each-standard/best-practices-for-all-ddex-standards/guidance-on-releaseresourcework-metadata/communicating-stems/) +- Other implementation details from above, including verifying file hashes +- Long-term UX from + [here](https://www.notion.so/DDEX-Artist-Facing-UX-d204863533fe4e3b9900e6a006620dba?pvs=21) + (displaying distributors to choose from) and account creation from the same doc + +--- diff --git a/docs/docusaurus.config.js b/docs/docusaurus.config.js index fbf19d053f3..dc2e6f839eb 100644 --- a/docs/docusaurus.config.js +++ b/docs/docusaurus.config.js @@ -87,6 +87,11 @@ const config = { to: '/node-operator/overview', position: 'right', }, + { + label: 'Distributors', + to: '/distributors/introduction/overview', + position: 'right', + }, { label: 'Reference', to: '/reference/overview', diff --git a/docs/sidebars.js b/docs/sidebars.js index 65b691e56a9..89d05ea0d08 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -74,6 +74,30 @@ module.exports = { }, ], + distributors: [ + { + type: 'category', + label: 'Introduction', + items: ['distributors/introduction/overview'], + collapsed: false, + }, + { + type: 'category', + label: 'Specification', + items: ['distributors/specification/overview', 'distributors/specification/ern3'], + collapsed: false, + }, + // { + // type: 'category', + // label: 'Run a DDEX Server', + // items: [ + // 'distributors/run-a-server/overview', + // 'distributors/run-a-server/run-a-ddex-server', + // ], + // collapsed: false, + // }, + ], + node_operators: [ { type: 'category', From ef354b97e9d707417efc7b8312c468095b8c835e Mon Sep 17 00:00:00 2001 From: Raymond Jacobson Date: Thu, 4 Apr 2024 16:07:07 -0700 Subject: [PATCH 02/12] [DVRL-23] Flesh out distributors page (#8028) --- .../distributors/introduction/overview.mdx | 18 +- .../run-a-server/run-a-ddex-server.mdx | 24 - .../{run-a-server => self-serve}/overview.mdx | 11 +- .../self-serve/run-a-ddex-server.mdx | 39 ++ docs/docs/distributors/specification/ern3.mdx | 202 +++++++-- docs/docs/distributors/specification/ern4.mdx | 9 + .../distributors/specification/overview.mdx | 328 ++------------ docs/i18n/en/code.json | 420 ++++++++++++++++++ .../options.json | 14 + .../current.json | 70 +++ .../en/docusaurus-theme-classic/navbar.json | 30 ++ docs/sidebars.js | 20 +- docs/src/css/custom.css | 17 +- 13 files changed, 822 insertions(+), 380 deletions(-) delete mode 100644 docs/docs/distributors/run-a-server/run-a-ddex-server.mdx rename docs/docs/distributors/{run-a-server => self-serve}/overview.mdx (57%) create mode 100644 docs/docs/distributors/self-serve/run-a-ddex-server.mdx create mode 100644 docs/docs/distributors/specification/ern4.mdx create mode 100644 docs/i18n/en/code.json create mode 100644 docs/i18n/en/docusaurus-plugin-content-blog/options.json create mode 100644 docs/i18n/en/docusaurus-plugin-content-docs/current.json create mode 100644 docs/i18n/en/docusaurus-theme-classic/navbar.json diff --git a/docs/docs/distributors/introduction/overview.mdx b/docs/docs/distributors/introduction/overview.mdx index c784e585de2..bea3c481b03 100644 --- a/docs/docs/distributors/introduction/overview.mdx +++ b/docs/docs/distributors/introduction/overview.mdx @@ -1,8 +1,8 @@ --- id: overview -title: DDEX with Audius -pagination_label: DDEX with Audius -sidebar_label: DDEX with Audius +title: Distributing Content to Audius +pagination_label: Distributing Content to Audius +sidebar_label: Overview description: Audius Protocol Documentation --- @@ -15,6 +15,10 @@ Visit [ddex.audius.co](https://ddex.audius.co) and check the ::: +Audius supports bulk content ingestion via the DDEX standard. + +If you're looking to build your own ingestion tooling, get started with the [Audius SDK](../../developers/sdk/overview). + ## What is DDEX Digital Data Exchange (or "DDEX") is an international standards-setting organization that was formed @@ -36,5 +40,9 @@ supply chain more efficiently by: ## Open Source -Like many Audius projects, all of the code is open source and available on -[GitHub](https://github.com/AudiusProject/ddex) +All DDEX ingestion code & libraries are open source and available on +[GitHub](https://github.com/AudiusProject/audius-protocol/tree/main/packages/ddex). + +You may clone and self-operate your own Audius compatible DDEX ingestion server, which provides a web +interface to deliver files, manage uploads, and track success. Under the hood, DDEX ingestion uses +the [Audius SDK](../../developers/sdk/overview) to process and upload tracks. diff --git a/docs/docs/distributors/run-a-server/run-a-ddex-server.mdx b/docs/docs/distributors/run-a-server/run-a-ddex-server.mdx deleted file mode 100644 index 1e2f4ee4039..00000000000 --- a/docs/docs/distributors/run-a-server/run-a-ddex-server.mdx +++ /dev/null @@ -1,24 +0,0 @@ ---- -id: run-a-ddex-server -title: Running a Server -pagination_label: Running a Server -sidebar_label: Running a Server -description: Audius Protocol Documentation -draft: true ---- - -import useBaseUrl from '@docusaurus/useBaseUrl' - -:::info Coming Soon! - -Still working on this one, but check back soon for updates on how to run our own DDEX Server. - -::: - -## Instructions - -- Go to audius-docker-compose - - Should this be audius-d? -- Run install script -- Set env vars - - Go to [DDEX README](https://github.com/AudiusProject/ddex) in audius-protocol and diff --git a/docs/docs/distributors/run-a-server/overview.mdx b/docs/docs/distributors/self-serve/overview.mdx similarity index 57% rename from docs/docs/distributors/run-a-server/overview.mdx rename to docs/docs/distributors/self-serve/overview.mdx index 450aebbfc19..ab9df4188e4 100644 --- a/docs/docs/distributors/run-a-server/overview.mdx +++ b/docs/docs/distributors/self-serve/overview.mdx @@ -4,13 +4,16 @@ title: Overview pagination_label: Overview sidebar_label: Overview description: Audius Protocol Documentation -unlisted: true --- import useBaseUrl from '@docusaurus/useBaseUrl' -:::info Coming Soon! +--- + +Content can be ingested into the Audius network by directly operating your own DDEX ingestion server. + +:::info -Still working on this one, but check back soon for updates on how to run our own DDEX Server. +More details soon -::: +::: \ No newline at end of file diff --git a/docs/docs/distributors/self-serve/run-a-ddex-server.mdx b/docs/docs/distributors/self-serve/run-a-ddex-server.mdx new file mode 100644 index 00000000000..9153ed698ef --- /dev/null +++ b/docs/docs/distributors/self-serve/run-a-ddex-server.mdx @@ -0,0 +1,39 @@ +--- +id: run-a-ddex-server +title: Running a DDEX Ingestion Server +pagination_label: Running a Server +sidebar_label: Running a Server +description: Audius Protocol Documentation +--- + +import useBaseUrl from '@docusaurus/useBaseUrl' + +:::info Coming Soon! + +Under construction. Please use as your own risk! 🚧 + +Check back soon for updates on how to run and operate own DDEX Ingestion Server. + +::: + +## Instructions + +1. Provision a new machine following. We recommend: + - Ubuntu + - 8 CPUs + - 16 to 32GB Memory + +2. Visit [audius-docker-compose](https://github.com/AudiusProject/audius-docker-compose) and +run the install script to set up your Audius environment on your provisioned machine. + +3. Follow the instructions in the [audius-protocol](https://github.com/AudiusProject/audius-protocol/tree/main/packages/ddex) +repository to set the appropriate environment variables + +4. Start the DDEX Ingestion Server + +``` +audius-cli launch ddex +``` + +Your server will now be available at localhost:80 and is exposed via self-signed SSL on :443 if `DDEX_URL` +is set. diff --git a/docs/docs/distributors/specification/ern3.mdx b/docs/docs/distributors/specification/ern3.mdx index bcfec3e7878..5dc1025b69e 100644 --- a/docs/docs/distributors/specification/ern3.mdx +++ b/docs/docs/distributors/specification/ern3.mdx @@ -3,44 +3,25 @@ id: ern3 title: ERN3 pagination_label: ERN3 sidebar_label: ERN3 -description: Audius Protocol Documentation +description: Support for ERN3 --- import useBaseUrl from '@docusaurus/useBaseUrl' -## General Guidance +# ERN3 -- Audius only accepts price information using absolute prices (e.g. via `WholesalePricePerUnit`). - Price codes will be ignored (e.g. `PriceType`). -- Audius also does not support `ValidityPeriod` `EndDate`s. This includes using `EndDate` to specify - multiple `ValidityPeriod`s with different prices. We can only parse 1 `ValidityPeriod` - `StartDate`. -- Audius only accepts the `Worldwide` `TerritoryCode`. -- `NonInteractiveStream` is not supported. -- A `ReleaseDeal` is required with a `DealReleaseReference` to each track on an album. -- A `ReleaseDeal` is not required with a `DealReleaseReference` to an album release. If an album - deal is not specified, the album defaults to being free to stream, but each of its tracks is - configured according to the track’s `ReleaseDeal` `DealTerms`. +[DDEX ERN3 Knowledge Base](https://kb.ddex.net/implementing-each-standard/electronic-release-notification-message-suite-(ern)/ern-3-explained/) ---- - -## Albums - - - -Audius accepts the following DDEX `Deal`s for **album** releases (details are the same as the corr. -deals in the tracks section below): +The following `Deal` types are supported for distribution to Audius. `Deal` types provided outside of +the provided list will be ignored. -1. Stream for free (not downloadable) -2. Stream gated by premium/USDC (artist-defined payment amount) (not downloadable) - ---- +If your use case extends beyond the supported `Deal` types outlined below, please contact `support@audius.co`. ## Tracks Audius accepts the following DDEX `Deal`s for **track** releases: -### Stream for free (not downloadable) +### Free To Stream 1. `CommercialModelType`: `FreeOfChargeModel` 2. `UseType`: `Stream` or `OnDemandStream` @@ -65,7 +46,7 @@ Audius accepts the following DDEX `Deal`s for **track** releases: ``` -### Stream gated by premium/USDC (artist-defined payment amount) (not downloadable) +### Pay Gated Stream 1. `CommercialModelType`: `PayAsYouGoModel` 2. `UseType`: `Stream` or `OnDemandStream` @@ -94,7 +75,32 @@ Audius accepts the following DDEX `Deal`s for **track** releases: ``` -### Stream gated by NFT (not downloadable) +### Follow Gated Stream + +1. `CommercialModelType`: `UserDefined` (`FollowGated`) +2. `UseType`: `Stream` or `OnDemandStream` +3. `PriceType`: not supported +4. `WholesalePricePerUnit`: N/A +5. `ValidityPeriod` + 1. `StartDate`: any +6. `TerritoryCode`: `Worldwide` + +```xml + + + UserDefined + + OnDemandStream + + Worldwide + + 2023-09-02 + + + +``` + +### NFT Gated Stream 1. `CommercialModelType`: `UserDefined` (`NFTGated`) 2. `UseType`: `Stream` or `OnDemandStream` @@ -155,9 +161,9 @@ Audius accepts the following DDEX `Deal`s for **track** releases: ``` -### Stream gated by follow (not downloadable) +### $AUDIO Tip Gated Stream -1. `CommercialModelType`: `UserDefined` (`FollowGated`) +1. `CommercialModelType`: `UserDefined` (`TipGated`) 2. `UseType`: `Stream` or `OnDemandStream` 3. `PriceType`: not supported 4. `WholesalePricePerUnit`: N/A @@ -168,7 +174,7 @@ Audius accepts the following DDEX `Deal`s for **track** releases: ```xml - UserDefined + UserDefined OnDemandStream @@ -180,10 +186,16 @@ Audius accepts the following DDEX `Deal`s for **track** releases: ``` -### Stream gated by tip (not downloadable) +### Free To Download -1. `CommercialModelType`: `UserDefined` (`TipGated`) -2. `UseType`: `Stream` or `OnDemandStream` +:::info Downloadable content is streamable. + +If you can download it, you can stream it. + +::: + +1. `CommercialModelType`: `FreeOfChargeModel` +2. `UseType`: `Stream` or `OnDemandStream`, `PermanentDownload` 3. `PriceType`: not supported 4. `WholesalePricePerUnit`: N/A 5. `ValidityPeriod` @@ -193,9 +205,10 @@ Audius accepts the following DDEX `Deal`s for **track** releases: ```xml - UserDefined + FreeOfChargeModel OnDemandStream + PermanentDownload Worldwide @@ -205,7 +218,7 @@ Audius accepts the following DDEX `Deal`s for **track** releases: ``` -### Download for free +### Pay Gated Download :::info Downloadable content is streamable. @@ -213,10 +226,10 @@ If you can download it, you can stream it. ::: -1. `CommercialModelType`: `FreeOfChargeModel` +1. `CommercialModelType`: `PayAsYouGoModel` 2. `UseType`: `Stream` or `OnDemandStream`, `PermanentDownload` 3. `PriceType`: not supported -4. `WholesalePricePerUnit`: N/A +4. `WholesalePricePerUnit`: any USD amount 5. `ValidityPeriod` 1. `StartDate`: any 6. `TerritoryCode`: `Worldwide` @@ -224,12 +237,16 @@ If you can download it, you can stream it. ```xml - FreeOfChargeModel + PayAsYouGoModel OnDemandStream PermanentDownload Worldwide + + 1.0 + ... + 2023-09-02 @@ -237,7 +254,7 @@ If you can download it, you can stream it. ``` -### Download gated by premium/USDC (artist defined payment amount) +### Follow Gated Download :::info Downloadable content is streamable. @@ -245,10 +262,10 @@ If you can download it, you can stream it. ::: -1. `CommercialModelType`: `PayAsYouGoModel` +1. `CommercialModelType`: `UserDefined` (`FollowGated`) 2. `UseType`: `Stream` or `OnDemandStream`, `PermanentDownload` 3. `PriceType`: not supported -4. `WholesalePricePerUnit`: any USD amount +4. `WholesalePricePerUnit`: N/A 5. `ValidityPeriod` 1. `StartDate`: any 6. `TerritoryCode`: `Worldwide` @@ -256,12 +273,68 @@ If you can download it, you can stream it. ```xml - PayAsYouGoModel + UserDefined OnDemandStream PermanentDownload Worldwide + + 2023-09-02 + + + +``` + +--- + +## Albums + +Audius accepts the following DDEX `Deal`s for **album** releases + +### Free To Stream + +1. `CommercialModelType`: `FreeOfChargeModel` +2. `UseType`: `Stream` or `OnDemandStream` +3. `PriceType`: not supported +4. `WholesalePricePerUnit`: N/A +5. `ValidityPeriod` + 1. `StartDate`: any +6. `TerritoryCode`: `Worldwide` + +```xml + + + FreeOfChargeModel + + OnDemandStream + + Worldwide + + 2023-09-02 + + + +``` + +### Pay Gated Stream + +1. `CommercialModelType`: `PayAsYouGoModel` +2. `UseType`: `Stream` or `OnDemandStream` +3. `PriceType`: not supported +4. `WholesalePricePerUnit`: any nonzero USD amount +5. `ValidityPeriod` + 1. `StartDate`: any +6. `TerritoryCode`: `Worldwide` + +```xml + + + PayAsYouGoModel + + OnDemandStream + + Worldwide 1.0 ... @@ -273,7 +346,7 @@ If you can download it, you can stream it. ``` -### Download gated by follow +### Free To Download :::info Downloadable content is streamable. @@ -281,7 +354,7 @@ If you can download it, you can stream it. ::: -1. `CommercialModelType`: `UserDefined` (`FollowGated`) +1. `CommercialModelType`: `FreeOfChargeModel` 2. `UseType`: `Stream` or `OnDemandStream`, `PermanentDownload` 3. `PriceType`: not supported 4. `WholesalePricePerUnit`: N/A @@ -292,7 +365,7 @@ If you can download it, you can stream it. ```xml - UserDefined + FreeOfChargeModel OnDemandStream PermanentDownload @@ -304,3 +377,40 @@ If you can download it, you can stream it. ``` + +### Pay Gated Download + +:::info Downloadable content is streamable. + +If you can download it, you can stream it. + +::: + +1. `CommercialModelType`: `PayAsYouGoModel` +2. `UseType`: `Stream` or `OnDemandStream`, `PermanentDownload` +3. `PriceType`: not supported +4. `WholesalePricePerUnit`: any USD amount +5. `ValidityPeriod` + 1. `StartDate`: any +6. `TerritoryCode`: `Worldwide` + +```xml + + + PayAsYouGoModel + + OnDemandStream + PermanentDownload + + Worldwide + + 1.0 + ... + + + 2023-09-02 + + + +``` + diff --git a/docs/docs/distributors/specification/ern4.mdx b/docs/docs/distributors/specification/ern4.mdx new file mode 100644 index 00000000000..b0acbad5ac2 --- /dev/null +++ b/docs/docs/distributors/specification/ern4.mdx @@ -0,0 +1,9 @@ +--- +id: ern4 +title: ERN4 🚧 +pagination_label: ERN4 🚧 +sidebar_label: ERN4 🚧 +description: Support for ERN4 +--- + +Coming Soon \ No newline at end of file diff --git a/docs/docs/distributors/specification/overview.mdx b/docs/docs/distributors/specification/overview.mdx index e56a4aa17a9..54c7caa30eb 100644 --- a/docs/docs/distributors/specification/overview.mdx +++ b/docs/docs/distributors/specification/overview.mdx @@ -1,316 +1,66 @@ --- id: overview -title: DDEX Specification -pagination_label: DDEX Specification -sidebar_label: DDEX Specification -description: Audius Protocol Documentation -draft: true +title: DDEX Best Practices +pagination_label: DDEX Best Practices +sidebar_label: DDEX Best Practices +description: DDEX best practices for delivering DDEX to Audius --- import useBaseUrl from '@docusaurus/useBaseUrl' -## Schema +## General Guidance -### Mapping Audius metadata to DDEX fields +:::info Delivery processing -This depends on the ERN version. Mapping for our Sony example (ERN 3.81): - -:::note Each Release has multiple `ReleaseDetailsByTerritory` elements - -Audius only uses the one with `Worldwide`. Similarly, for each -`SoundRecording` we only use the `SoundRecordingDetailsByTerritory` where TerritoryCode is -Worldwide. +[TikiLabs](https://tikilabs.com) is a facilitator of distributing DDEX directly to the Audius Protocol +For inquiries or support, reach out at support@audius.co. ::: -| Audius | DDEX | Notes | -| ------------------------------------------------------------------ | ----------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| releaseDate | /ReleaseList/Release/GlobalOriginalReleaseDate | TODO: This is apparently deprecated. Probably needs to change to use a date from DealList | -| duration | /ResourceList/SoundRecording/Duration | Parsed as ISO 8601. Falls back to /ReleaseList/Release/Duration from the release with a matching ResourceReference | -| title | | -| artist | | -| preview | | -| isrc | | -| genre | | | -| | | We don't have the concept of "Disks" which some albums have multiple of. For now disks are flattened into the same album with no differentiation. See | -| description | | There was some element I remember being similar to description, but in the Sony example I didn’t see any actual description. | -| iswc | | | -| license | | | -| previewStartSeconds | | DDEX supports preview duration, but Audius sets it to exactly 30 seconds. | -| isUnlisted | | Probably parse from DealList. See https://kb.ddex.net/implementing-each-standard/best-practices-for-all-ddex-standards/deals-and-commercial-aspects/availability-and-visibility/ | -| fieldVisibility.\* (moods, tags, genre, share, playCount, remixes) | | Probably parse from DealList. See https://kb.ddex.net/implementing-each-standard/best-practices-for-all-ddex-standards/deals-and-commercial-aspects/availability-and-visibility/ | -| remixOf | | Possible equivalent in DDEX RelatedResource. See https://kb.ddex.net/implementing-each-standard/best-practices-for-all-ddex-standards/guidance-on-releaseresourcework-metadata/linking-different-releases-and-resources/ and https://kb.ddex.net/implementing-each-standard/best-practices-for-all-ddex-standards/guidance-on-contributors,-artists-and-writers/communicating-remixes-and-remixers/ | -| origFilename | | Possible equivalent in DDEX | -| isOriginalAvailable | | Possible equivalent in DDEX | -| origFileCid | | Possible equivalent in DDEX | -| streamConditions | | Possible equivalent in DealList in the future | -| isStreamGated | | Possible equivalent in DealList in the future | -| isDownloadGated | | Possible equivalent in DealList in the future | -| downloadConditions | | Possible equivalent in DealList in the future | -| download.cid | | Possible equivalent in DealList in the future | -| download.isDownloadable | | Possible equivalent in DealList in the future | -| download.requiresFollow | | Possible equivalent in DealList in the future | -| mood | | No equivalent in DDEX | -| tags | | No equivalent in DDEX | -| aiAttributionUserId | | No equivalent in DDEX | -| | /ReleaseList/Release/ReleaseDetailsByTerritory[TerritoryCode="Worldwide"]/PLine | TODO: This has copyright data which we likely want to add to the track/album’s description. Although https://kb.ddex.net/implementing-each-standard/best-practices-for-all-ddex-standards/guidance-on-releaseresourcework-metadata/pline-and-cline/ says it’s not mandatory | -| | /ReleaseList/Release/ReleaseDetailsByTerritory[TerritoryCode="Worldwide"]/LabelName | | -| | other IDs (GRid, UPC, etc) | All possible options are enumerated https://kb.ddex.net/implementing-each-standard/best-practices-for-all-ddex-standards/guidance-on-identifiers-and-iso-codes-lists/communication-of-identifiers-in-ddex-messages/ | -| | ParentalWarningType | No equivalent in Audius | - -### Handling deliveries with multiple `` elements - -My understanding is that we should parse out each one and return a single album (assuming it’s -marked as an album and not random unrelated tracks). - -However, we have to also parse each `/DealList/ReleaseDeal` and set the visibility metadata of each -track based on if its the ReleaseDeal’s `DealReleaseReference` matches the track. See -[here](https://kb.ddex.net/implementing-each-standard/best-practices-for-all-ddex-standards/guidance-on-releaseresourcework-metadata/trackreleases/) -and -[here](https://kb.ddex.net/implementing-each-standard/best-practices-for-all-ddex-standards/guidance-on-releaseresourcework-metadata/release-types-for-trackreleases/). - ---- - -## Miscellaneous - -### What’s our DDEX Party Identifier (DPID)? - -Tiki Labs, Inc. has a DPID of `PA-DPIDA-202401120D-9`. According to -[this](https://ddex.net/implementation/implementation-licence-and-ddex-party-identifiers/), a DPID -is something every company accepting deliveries needs to receive by signing -[this license](https://ddex.net/implementation/implementation-licence-terms-and-conditions/). - ---- - -## Open Questions - -### How does each `` map to Audius? - -According to -[this](https://kb.ddex.net/implementing-each-standard/best-practices-for-all-ddex-standards/guidance-on-releaseresourcework-metadata/primary-and-secondary-resources/), -we **must** have one of these ``s in order to make a track visible. +- ERN3 is the preferred DDEX specification for bulk ingestion into Audius. See the [ERN3 details](./ern3) for more details around submission choreography. +- Audius only accepts price information using absolute prices (e.g. via `WholesalePricePerUnit`). + Price codes will be ignored (e.g. `PriceType`). +- Audius also does not support `ValidityPeriod` `EndDate`s. This includes using `EndDate` to specify + multiple `ValidityPeriod`s with different prices. We can only parse 1 `ValidityPeriod` + `StartDate`. +- Audius currently only accepts the `Worldwide` `TerritoryCode`. Territory support for controlled streaming is coming soon! 🌎 +- `NonInteractiveStream` is not supported. +- A `ReleaseDeal` is required with a `DealReleaseReference` to each track on an album. +- A `ReleaseDeal` is not required with a `DealReleaseReference` to an album release. If an album + deal is not specified, the album defaults to being free to stream, but each of its tracks is + configured according to the track’s `ReleaseDeal` `DealTerms`. -None of the existing options I’ve seen for deal types make sense for Audius: +## Metadata Mapping -1. `PayAsYouGoModel`: “A CommercialModel where the Service or Product offering is financed by - revenue generated from payment (set at any level but not zero) for each Usage which the Customer - makes of the Service or Product.” -2. `SubscriptionModel`: A CommercialModel where the Service or Product offering is financed by - revenue generated from a Customer Subscription. -3. `AdvertisementSupportedModel`: `` +:::info The following is provided based on ERN3.8 -UseTypes I’ve seen: +Please note that exact DDEX fields will depend on the specific ERN version. -1. `Stream` -2. `NonInteractiveStream` (radio, no fast forward or playlist / search + play on demand. skip OK) -3. `OnDemandStream` -4. `PermanentDownload` (what it sounds like - store locally is OK) -5. `ConditionalDownload` (like Spotify - as long as you’re subscribed you can download. offline - mode) - -Example Deal: - -```bash - - - AdvertisementSupportedModel - - Stream - - - 2018-01-10 - - - -``` - -Another example: - -```bash - - - PayAsYouGoModel - - PermanentDownload - - - B89 - - - 2023-09-02 - - 2023-09-02 - 2023-09-02 - 2023-09-02 - 2023-09-02 - - -``` - -Third example: +::: -```bash - - - SubscriptionModel - - ConditionalDownload - NonInteractiveStream - OnDemandStream - - - 2023-09-02 - - - -``` +### Required -Fourth example: -```bash - - - PayAsYouGoModel - - PermanentDownload - - Worldwide - - FRONT - FRONT - - - 2021-03-16 - - - -``` +| Audius | DDEX | Notes | +| ------------------------------------------------------------------ | ----------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| releaseDate | /ReleaseList/Release/GlobalOriginalReleaseDate | TODO: This is apparently deprecated. Probably needs to change to use a date from DealList | +| duration | /ResourceList/SoundRecording/Duration | Parsed as ISO 8601. Falls back to /ReleaseList/Release/Duration from the release with a matching ResourceReference | -### Proposed (new) DealTypes for Audius types: -1. Stream for free: - 1. CommercialModelType: `FreeOfChargeModel` - 2. UseType options: `Stream` - 3. PriceType options: N/A - 4. PriceRangeType options: - 5. WholeSalePricePerUnit vs retail price (label has to be paid the wholesale price, and we have - to mark it up (retail) to be able to make money): -2. Stream gated by premium/USDC (artist-defined payment amount) - 1. CommercialModelType: `PayAsYouGoModel` - 2. UseType options: `Stream` - 3. PriceType options: - 4. PriceRangeType options: - 5. WholeSalePricePerUnit vs retail price (label has to be paid the wholesale price, and we have - to mark it up (retail) to be able to make money): -3. Stream gated by NFT - 1. CommercialModelType: `UserDefined` (`NFTGated`) - 2. UseType options: `Stream` - 3. PriceType options: - 4. PriceRangeType options: - 5. WholeSalePricePerUnit vs retail price (label has to be paid the wholesale price, and we have - to mark it up (retail) to be able to make money): -4. Stream gated by follow - 1. CommercialModelType: `UserDefined` (`FollowGated`) - 2. UseType options: `Stream` - 3. PriceType options: - 4. PriceRangeType options: - 5. WholeSalePricePerUnit vs retail price (label has to be paid the wholesale price, and we have - to mark it up (retail) to be able to make money): -5. Stream gated by tip - 1. CommercialModelType: `UserDefined` (`TipGated`) or `PayAsYouGoModel`? - 2. UseType options: `Stream` - 3. PriceType options: - 4. PriceRangeType options: - 5. WholeSalePricePerUnit vs retail price (label has to be paid the wholesale price, and we have - to mark it up (retail) to be able to make money): -6. Download for free - 1. CommercialModelType: `FreeOfChargeModel` - 2. UseType options: `Stream`, `PermanentDownload` - 3. PriceType options: N/A - 4. PriceRangeType options: N/A - 5. WholeSalePricePerUnit vs retail price (label has to be paid the wholesale price, and we have - to mark it up (retail) to be able to make money): N/A -7. Download gated by premium/USDC (artist defined payment amount) - 1. CommercialModelType: `PayAsYouGoModel` - 2. UseType options: `Stream`, `PermanentDownload` - 3. PriceType options: - 4. PriceRangeType options: - 5. WholeSalePricePerUnit vs retail price (label has to be paid the wholesale price, and we have - to mark it up (retail) to be able to make money): -8. Download gated by follow - 1. CommercialModelType: `UserDefined` (`FollowGated`) - 2. UseType options: `Stream`, `PermanentDownload` - 3. PriceType options: - 4. PriceRangeType options: - 5. WholeSalePricePerUnit vs retail price (label has to be paid the wholesale price, and we have - to mark it up (retail) to be able to make money): -9. (If you can’t stream it, you can’t download it) +### Optional -### How do we parse each ID? Which ID type is the primary differentiator? -There are different IDs that the XML can provide, like GRid, ICPN, CatalogNumber, ProprietaryId, and -more (all ID options are enumerated -[here](https://kb.ddex.net/implementing-each-standard/best-practices-for-all-ddex-standards/guidance-on-identifiers-and-iso-codes-lists/communication-of-identifiers-in-ddex-messages/)). -For now, we ignore them and only look at ISRC, which I don’t think is correct. +| Audius | DDEX | Notes | +| ------------------------------------------------------------------ | ----------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| releaseDate | /ReleaseList/Release/GlobalOriginalReleaseDate | TODO: This is apparently deprecated. Probably needs to change to use a date from DealList | +| duration | /ResourceList/SoundRecording/Duration | Parsed as ISO 8601. Falls back to /ReleaseList/Release/Duration from the release with a matching ResourceReference | -Tentative decision: According to -[this](https://kb.ddex.net/implementing-each-standard/best-practices-for-all-ddex-standards/guidance-on-releaseresourcework-metadata/trackreleases/), -we might need to at least store the GRid and ProprietaryId in the DDEX db somewhere for future -reference. We should support more ID fields in our metadata to index (see Ray’s comment above). -1. Is it acceptable to have 30 second previews when DDEX tells us exactly how long they should be? - - Context: We’re parsing out the data, but Audius is hardcoded to 30 second previews. This goes - against the variable lengths that different DDEX releases specify. -2. How do we want to support releases that have multiple artists? - - Context: According to - [this](https://kb.ddex.net/implementing-each-standard/best-practices-for-all-ddex-standards/guidance-on-contributors,-artists-and-writers/contributors,-artists-and-writers/) - and - [this](https://kb.ddex.net/implementing-each-standard/best-practices-for-all-ddex-standards/guidance-on-contributors,-artists-and-writers/information-on-displayartists,-displayartistnames,-contributors-and-indirectcontributors/), - we should use “Display Artist Name” which could actually be 2 artists like “Drake & The Weeknd” - so it wouldn’t match an account. Also, to support showing “ID” for artist and/or track for - things like music festival sets, I think we’d need to have some kind of decoupling between - display names and actual accounts. - - Tentative decision: add some more fields to index. See Ray’s comment above and - https://www.ifpi.org/wp-content/uploads/2020/08/GRid_Standard_v2_1.pdf -3. Do we need to upload an acknowledgement XML file for each delivery? - - Context: - [This](https://ernccloud.ddex.net/electronic-release-notification-message-suite-part-3%253A-choreographies-for-cloud-based-storage/5-release-by-release-profile/5.1-choreography/) - says we “shall” upload XML acknowledging exactly what was done for each release (to a separate - acknowledgements folder according to - [this](https://ernccloud.ddex.net/electronic-release-notification-message-suite-part-3%253A-choreographies-for-cloud-based-storage/5-release-by-release-profile/5.2-file-server-organisation/)). - Does Fuga require this or have any special constraints to be mindful of when uploading acks? -4. Do we need to handle separate territories? - - Context: For example, it looks like the Sony example DealList allows for downloading in some - countries but not others. -5. How should we handle all the other fields we don’t support? - - Context: See table above. The main ones are LabelName and PLineText (copyright info). Maybe we - just add the PLineText to the track/album description? -6. Our genres don’t match the genres in DDEX. For example, Sony sent a delivery with “Hip hop” while - our equivalent is “Hip-hop/Rap.” - - Context: For now, we have an explicit mapping, which will break any time there’s a new genre. - Do we want to keep on this explicit mapping path? +### Unused -## Main areas of work remaining -- Previews: see question above - we’re parsing out preview info, but the backend is hardcoded to 30 - second previews instead of whatever variable length each release specifies -- Making metadata un-editable by artist -- Processing updates and deletes. One potential blocker on this is that we don’t have a “replacing - of audio” feature. See - [here](https://kb.ddex.net/implementing-each-standard/best-practices-for-all-ddex-standards/guidance-on-message-exchange-protocols-and-choreographies/update-indicator/) - and - [here](https://kb.ddex.net/implementing-each-standard/best-practices-for-all-ddex-standards/guidance-on-message-exchange-protocols-and-choreographies/differentiating-inserts-from-updates/) - for DDEX spec details when implementing. -- According to - [this](https://kb.ddex.net/implementing-each-standard/best-practices-for-all-ddex-standards/guidance-on-message-exchange-protocols-and-choreographies/no-resources-in-initial-delivery/), - we should allow a release to not contain all the files (ie, the first delivery only has metadata, - and a future delivery will include the actual assets). Also see - [here](https://kb.ddex.net/implementing-each-standard/best-practices-for-all-ddex-standards/guidance-on-releaseresourcework-metadata/ern-message-without-resources/) -- Maybe support - [stems](https://kb.ddex.net/implementing-each-standard/best-practices-for-all-ddex-standards/guidance-on-releaseresourcework-metadata/communicating-stems/) -- Other implementation details from above, including verifying file hashes -- Long-term UX from - [here](https://www.notion.so/DDEX-Artist-Facing-UX-d204863533fe4e3b9900e6a006620dba?pvs=21) - (displaying distributors to choose from) and account creation from the same doc +| Audius | DDEX | Notes | +| ------------------------------------------------------------------ | ----------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| releaseDate | /ReleaseList/Release/GlobalOriginalReleaseDate | TODO: This is apparently deprecated. Probably needs to change to use a date from DealList | +| duration | /ResourceList/SoundRecording/Duration | Parsed as ISO 8601. Falls back to /ReleaseList/Release/Duration from the release with a matching ResourceReference | ---- diff --git a/docs/i18n/en/code.json b/docs/i18n/en/code.json new file mode 100644 index 00000000000..71f221e8427 --- /dev/null +++ b/docs/i18n/en/code.json @@ -0,0 +1,420 @@ +{ + "theme.ErrorPageContent.title": { + "message": "This page crashed.", + "description": "The title of the fallback page when the page crashed" + }, + "theme.BackToTopButton.buttonAriaLabel": { + "message": "Scroll back to top", + "description": "The ARIA label for the back to top button" + }, + "theme.blog.paginator.navAriaLabel": { + "message": "Blog list page navigation", + "description": "The ARIA label for the blog pagination" + }, + "theme.blog.paginator.newerEntries": { + "message": "Newer Entries", + "description": "The label used to navigate to the newer blog posts page (previous page)" + }, + "theme.blog.paginator.olderEntries": { + "message": "Older Entries", + "description": "The label used to navigate to the older blog posts page (next page)" + }, + "theme.blog.archive.title": { + "message": "Archive", + "description": "The page & hero title of the blog archive page" + }, + "theme.blog.archive.description": { + "message": "Archive", + "description": "The page & hero description of the blog archive page" + }, + "theme.blog.post.paginator.navAriaLabel": { + "message": "Blog post page navigation", + "description": "The ARIA label for the blog posts pagination" + }, + "theme.blog.post.paginator.newerPost": { + "message": "Newer Post", + "description": "The blog post button label to navigate to the newer/previous post" + }, + "theme.blog.post.paginator.olderPost": { + "message": "Older Post", + "description": "The blog post button label to navigate to the older/next post" + }, + "theme.blog.post.plurals": { + "message": "One post|{count} posts", + "description": "Pluralized label for \"{count} posts\". Use as much plural forms (separated by \"|\") as your language support (see https://www.unicode.org/cldr/cldr-aux/charts/34/supplemental/language_plural_rules.html)" + }, + "theme.blog.tagTitle": { + "message": "{nPosts} tagged with \"{tagName}\"", + "description": "The title of the page for a blog tag" + }, + "theme.tags.tagsPageLink": { + "message": "View All Tags", + "description": "The label of the link targeting the tag list page" + }, + "theme.docs.breadcrumbs.navAriaLabel": { + "message": "Breadcrumbs", + "description": "The ARIA label for the breadcrumbs" + }, + "theme.docs.DocCard.categoryDescription": { + "message": "{count} items", + "description": "The default description for a category card in the generated index about how many items this category includes" + }, + "theme.colorToggle.ariaLabel": { + "message": "Switch between dark and light mode (currently {mode})", + "description": "The ARIA label for the navbar color mode toggle" + }, + "theme.colorToggle.ariaLabel.mode.dark": { + "message": "dark mode", + "description": "The name for the dark color mode" + }, + "theme.colorToggle.ariaLabel.mode.light": { + "message": "light mode", + "description": "The name for the light color mode" + }, + "theme.docs.paginator.navAriaLabel": { + "message": "Docs pages", + "description": "The ARIA label for the docs pagination" + }, + "theme.docs.paginator.previous": { + "message": "Previous", + "description": "The label used to navigate to the previous doc" + }, + "theme.docs.paginator.next": { + "message": "Next", + "description": "The label used to navigate to the next doc" + }, + "theme.docs.versionBadge.label": { + "message": "Version: {versionLabel}" + }, + "theme.docs.tagDocListPageTitle.nDocsTagged": { + "message": "One doc tagged|{count} docs tagged", + "description": "Pluralized label for \"{count} docs tagged\". Use as much plural forms (separated by \"|\") as your language support (see https://www.unicode.org/cldr/cldr-aux/charts/34/supplemental/language_plural_rules.html)" + }, + "theme.docs.tagDocListPageTitle": { + "message": "{nDocsTagged} with \"{tagName}\"", + "description": "The title of the page for a docs tag" + }, + "theme.docs.versions.unreleasedVersionLabel": { + "message": "This is unreleased documentation for {siteTitle} {versionLabel} version.", + "description": "The label used to tell the user that he's browsing an unreleased doc version" + }, + "theme.docs.versions.unmaintainedVersionLabel": { + "message": "This is documentation for {siteTitle} {versionLabel}, which is no longer actively maintained.", + "description": "The label used to tell the user that he's browsing an unmaintained doc version" + }, + "theme.docs.versions.latestVersionSuggestionLabel": { + "message": "For up-to-date documentation, see the {latestVersionLink} ({versionLabel}).", + "description": "The label used to tell the user to check the latest version" + }, + "theme.docs.versions.latestVersionLinkLabel": { + "message": "latest version", + "description": "The label used for the latest version suggestion link label" + }, + "theme.common.editThisPage": { + "message": "Edit this page", + "description": "The link label to edit the current page" + }, + "theme.common.headingLinkTitle": { + "message": "Direct link to {heading}", + "description": "Title for link to heading" + }, + "theme.lastUpdated.atDate": { + "message": " on {date}", + "description": "The words used to describe on which date a page has been last updated" + }, + "theme.lastUpdated.byUser": { + "message": " by {user}", + "description": "The words used to describe by who the page has been last updated" + }, + "theme.lastUpdated.lastUpdatedAtBy": { + "message": "Last updated{atDate}{byUser}", + "description": "The sentence used to display when a page has been last updated, and by who" + }, + "theme.navbar.mobileVersionsDropdown.label": { + "message": "Versions", + "description": "The label for the navbar versions dropdown on mobile view" + }, + "theme.NotFound.title": { + "message": "Page Not Found", + "description": "The title of the 404 page" + }, + "theme.tags.tagsListLabel": { + "message": "Tags:", + "description": "The label alongside a tag list" + }, + "theme.AnnouncementBar.closeButtonAriaLabel": { + "message": "Close", + "description": "The ARIA label for close button of announcement bar" + }, + "theme.blog.sidebar.navAriaLabel": { + "message": "Blog recent posts navigation", + "description": "The ARIA label for recent posts in the blog sidebar" + }, + "theme.admonition.caution": { + "message": "caution", + "description": "The default label used for the Caution admonition (:::caution)" + }, + "theme.admonition.danger": { + "message": "danger", + "description": "The default label used for the Danger admonition (:::danger)" + }, + "theme.admonition.info": { + "message": "info", + "description": "The default label used for the Info admonition (:::info)" + }, + "theme.admonition.note": { + "message": "note", + "description": "The default label used for the Note admonition (:::note)" + }, + "theme.admonition.tip": { + "message": "tip", + "description": "The default label used for the Tip admonition (:::tip)" + }, + "theme.admonition.warning": { + "message": "warning", + "description": "The default label used for the Warning admonition (:::warning)" + }, + "theme.CodeBlock.copied": { + "message": "Copied", + "description": "The copied button label on code blocks" + }, + "theme.CodeBlock.copyButtonAriaLabel": { + "message": "Copy code to clipboard", + "description": "The ARIA label for copy code blocks button" + }, + "theme.CodeBlock.copy": { + "message": "Copy", + "description": "The copy button label on code blocks" + }, + "theme.CodeBlock.wordWrapToggle": { + "message": "Toggle word wrap", + "description": "The title attribute for toggle word wrapping button of code block lines" + }, + "theme.DocSidebarItem.expandCategoryAriaLabel": { + "message": "Expand sidebar category '{label}'", + "description": "The ARIA label to expand the sidebar category" + }, + "theme.DocSidebarItem.collapseCategoryAriaLabel": { + "message": "Collapse sidebar category '{label}'", + "description": "The ARIA label to collapse the sidebar category" + }, + "theme.NavBar.navAriaLabel": { + "message": "Main", + "description": "The ARIA label for the main navigation" + }, + "theme.NotFound.p1": { + "message": "We could not find what you were looking for.", + "description": "The first paragraph of the 404 page" + }, + "theme.NotFound.p2": { + "message": "Please contact the owner of the site that linked you to the original URL and let them know their link is broken.", + "description": "The 2nd paragraph of the 404 page" + }, + "theme.TOCCollapsible.toggleButtonLabel": { + "message": "On this page", + "description": "The label used by the button on the collapsible TOC component" + }, + "theme.blog.post.readMore": { + "message": "Read More", + "description": "The label used in blog post item excerpts to link to full blog posts" + }, + "theme.blog.post.readMoreLabel": { + "message": "Read more about {title}", + "description": "The ARIA label for the link to full blog posts from excerpts" + }, + "theme.blog.post.readingTime.plurals": { + "message": "One min read|{readingTime} min read", + "description": "Pluralized label for \"{readingTime} min read\". Use as much plural forms (separated by \"|\") as your language support (see https://www.unicode.org/cldr/cldr-aux/charts/34/supplemental/language_plural_rules.html)" + }, + "theme.navbar.mobileLanguageDropdown.label": { + "message": "Languages", + "description": "The label for the mobile language switcher dropdown" + }, + "theme.docs.sidebar.collapseButtonTitle": { + "message": "Collapse sidebar", + "description": "The title attribute for collapse button of doc sidebar" + }, + "theme.docs.sidebar.collapseButtonAriaLabel": { + "message": "Collapse sidebar", + "description": "The title attribute for collapse button of doc sidebar" + }, + "theme.docs.breadcrumbs.home": { + "message": "Home page", + "description": "The ARIA label for the home page in the breadcrumbs" + }, + "theme.docs.sidebar.closeSidebarButtonAriaLabel": { + "message": "Close navigation bar", + "description": "The ARIA label for close button of mobile sidebar" + }, + "theme.docs.sidebar.navAriaLabel": { + "message": "Docs sidebar", + "description": "The ARIA label for the sidebar navigation" + }, + "theme.docs.sidebar.toggleSidebarButtonAriaLabel": { + "message": "Toggle navigation bar", + "description": "The ARIA label for hamburger menu button of mobile navigation" + }, + "theme.docs.sidebar.expandButtonTitle": { + "message": "Expand sidebar", + "description": "The ARIA label and title attribute for expand button of doc sidebar" + }, + "theme.docs.sidebar.expandButtonAriaLabel": { + "message": "Expand sidebar", + "description": "The ARIA label and title attribute for expand button of doc sidebar" + }, + "theme.navbar.mobileSidebarSecondaryMenu.backButtonLabel": { + "message": "← Back to main menu", + "description": "The label of the back button to return to main menu, inside the mobile navbar sidebar secondary menu (notably used to display the docs sidebar)" + }, + "theme.SearchBar.seeAll": { + "message": "See all {count} results" + }, + "theme.SearchBar.label": { + "message": "Search", + "description": "The ARIA label and placeholder for search button" + }, + "theme.SearchModal.searchBox.resetButtonTitle": { + "message": "Clear the query", + "description": "The label and ARIA label for search box reset button" + }, + "theme.SearchModal.searchBox.cancelButtonText": { + "message": "Cancel", + "description": "The label and ARIA label for search box cancel button" + }, + "theme.SearchModal.startScreen.recentSearchesTitle": { + "message": "Recent", + "description": "The title for recent searches" + }, + "theme.SearchModal.startScreen.noRecentSearchesText": { + "message": "No recent searches", + "description": "The text when no recent searches" + }, + "theme.SearchModal.startScreen.saveRecentSearchButtonTitle": { + "message": "Save this search", + "description": "The label for save recent search button" + }, + "theme.SearchModal.startScreen.removeRecentSearchButtonTitle": { + "message": "Remove this search from history", + "description": "The label for remove recent search button" + }, + "theme.SearchModal.startScreen.favoriteSearchesTitle": { + "message": "Favorite", + "description": "The title for favorite searches" + }, + "theme.SearchModal.startScreen.removeFavoriteSearchButtonTitle": { + "message": "Remove this search from favorites", + "description": "The label for remove favorite search button" + }, + "theme.SearchModal.errorScreen.titleText": { + "message": "Unable to fetch results", + "description": "The title for error screen of search modal" + }, + "theme.SearchModal.errorScreen.helpText": { + "message": "You might want to check your network connection.", + "description": "The help text for error screen of search modal" + }, + "theme.SearchModal.footer.selectText": { + "message": "to select", + "description": "The explanatory text of the action for the enter key" + }, + "theme.SearchModal.footer.selectKeyAriaLabel": { + "message": "Enter key", + "description": "The ARIA label for the Enter key button that makes the selection" + }, + "theme.SearchModal.footer.navigateText": { + "message": "to navigate", + "description": "The explanatory text of the action for the Arrow up and Arrow down key" + }, + "theme.SearchModal.footer.navigateUpKeyAriaLabel": { + "message": "Arrow up", + "description": "The ARIA label for the Arrow up key button that makes the navigation" + }, + "theme.SearchModal.footer.navigateDownKeyAriaLabel": { + "message": "Arrow down", + "description": "The ARIA label for the Arrow down key button that makes the navigation" + }, + "theme.SearchModal.footer.closeText": { + "message": "to close", + "description": "The explanatory text of the action for Escape key" + }, + "theme.SearchModal.footer.closeKeyAriaLabel": { + "message": "Escape key", + "description": "The ARIA label for the Escape key button that close the modal" + }, + "theme.SearchModal.footer.searchByText": { + "message": "Search by", + "description": "The text explain that the search is making by Algolia" + }, + "theme.SearchModal.noResultsScreen.noResultsText": { + "message": "No results for", + "description": "The text explains that there are no results for the following search" + }, + "theme.SearchModal.noResultsScreen.suggestedQueryText": { + "message": "Try searching for", + "description": "The text for the suggested query when no results are found for the following search" + }, + "theme.SearchModal.noResultsScreen.reportMissingResultsText": { + "message": "Believe this query should return results?", + "description": "The text for the question where the user thinks there are missing results" + }, + "theme.SearchModal.noResultsScreen.reportMissingResultsLinkText": { + "message": "Let us know.", + "description": "The text for the link to report missing results" + }, + "theme.SearchModal.placeholder": { + "message": "Search docs", + "description": "The placeholder of the input of the DocSearch pop-up modal" + }, + "theme.SearchPage.documentsFound.plurals": { + "message": "One document found|{count} documents found", + "description": "Pluralized label for \"{count} documents found\". Use as much plural forms (separated by \"|\") as your language support (see https://www.unicode.org/cldr/cldr-aux/charts/34/supplemental/language_plural_rules.html)" + }, + "theme.SearchPage.existingResultsTitle": { + "message": "Search results for \"{query}\"", + "description": "The search page title for non-empty query" + }, + "theme.SearchPage.emptyResultsTitle": { + "message": "Search the documentation", + "description": "The search page title for empty query" + }, + "theme.SearchPage.inputPlaceholder": { + "message": "Type your search here", + "description": "The placeholder for search page input" + }, + "theme.SearchPage.inputLabel": { + "message": "Search", + "description": "The ARIA label for search page input" + }, + "theme.SearchPage.algoliaLabel": { + "message": "Search by Algolia", + "description": "The ARIA label for Algolia mention" + }, + "theme.SearchPage.noResultsText": { + "message": "No results were found", + "description": "The paragraph for empty search result" + }, + "theme.SearchPage.fetchingNewResults": { + "message": "Fetching new results...", + "description": "The paragraph for fetching new search results" + }, + "theme.ErrorPageContent.tryAgain": { + "message": "Try again", + "description": "The label of the button to try again rendering when the React error boundary captures an error" + }, + "theme.common.skipToMainContent": { + "message": "Skip to main content", + "description": "The skip to content label used for accessibility, allowing to rapidly navigate to main content with keyboard tab/enter navigation" + }, + "theme.tags.tagsPageTitle": { + "message": "Tags", + "description": "The title of the tag list page" + }, + "theme.unlistedContent.title": { + "message": "Unlisted page", + "description": "The unlisted content banner title" + }, + "theme.unlistedContent.message": { + "message": "This page is unlisted. Search engines will not index it, and only users having a direct link can access it.", + "description": "The unlisted content banner message" + } +} diff --git a/docs/i18n/en/docusaurus-plugin-content-blog/options.json b/docs/i18n/en/docusaurus-plugin-content-blog/options.json new file mode 100644 index 00000000000..9239ff706c2 --- /dev/null +++ b/docs/i18n/en/docusaurus-plugin-content-blog/options.json @@ -0,0 +1,14 @@ +{ + "title": { + "message": "Blog", + "description": "The title for the blog used in SEO" + }, + "description": { + "message": "Blog", + "description": "The description for the blog used in SEO" + }, + "sidebar.title": { + "message": "Recent posts", + "description": "The label for the left sidebar" + } +} diff --git a/docs/i18n/en/docusaurus-plugin-content-docs/current.json b/docs/i18n/en/docusaurus-plugin-content-docs/current.json new file mode 100644 index 00000000000..191957753c1 --- /dev/null +++ b/docs/i18n/en/docusaurus-plugin-content-docs/current.json @@ -0,0 +1,70 @@ +{ + "version.label": { + "message": "Next", + "description": "The label for version current" + }, + "sidebar.learn.category.Introduction": { + "message": "Introduction", + "description": "The label for category Introduction in sidebar learn" + }, + "sidebar.learn.category.Core Concepts": { + "message": "Core Concepts", + "description": "The label for category Core Concepts in sidebar learn" + }, + "sidebar.learn.category.Contributing": { + "message": "Contributing", + "description": "The label for category Contributing in sidebar learn" + }, + "sidebar.developers.category.Introduction": { + "message": "Introduction", + "description": "The label for category Introduction in sidebar developers" + }, + "sidebar.developers.category.Javascript SDK": { + "message": "Javascript SDK", + "description": "The label for category Javascript SDK in sidebar developers" + }, + "sidebar.developers.category.Guides": { + "message": "Guides", + "description": "The label for category Guides in sidebar developers" + }, + "sidebar.developers.category.The Graph": { + "message": "The Graph", + "description": "The label for category The Graph in sidebar developers" + }, + "sidebar.distributors.category.Introduction": { + "message": "Introduction", + "description": "The label for category Introduction in sidebar distributors" + }, + "sidebar.distributors.category.Specification": { + "message": "Specification", + "description": "The label for category Specification in sidebar distributors" + }, + "sidebar.distributors.category.Self Serve": { + "message": "Self Serve", + "description": "The label for category Self Serve in sidebar distributors" + }, + "sidebar.node_operators.category.Introduction": { + "message": "Introduction", + "description": "The label for category Introduction in sidebar node_operators" + }, + "sidebar.node_operators.category.Staking": { + "message": "Staking", + "description": "The label for category Staking in sidebar node_operators" + }, + "sidebar.node_operators.category.Run a Node": { + "message": "Run a Node", + "description": "The label for category Run a Node in sidebar node_operators" + }, + "sidebar.node_operators.category.Register a Node": { + "message": "Register a Node", + "description": "The label for category Register a Node in sidebar node_operators" + }, + "sidebar.reference.category.Introduction": { + "message": "Introduction", + "description": "The label for category Introduction in sidebar reference" + }, + "sidebar.reference.category.Protocol Dashboard": { + "message": "Protocol Dashboard", + "description": "The label for category Protocol Dashboard in sidebar reference" + } +} diff --git a/docs/i18n/en/docusaurus-theme-classic/navbar.json b/docs/i18n/en/docusaurus-theme-classic/navbar.json new file mode 100644 index 00000000000..a061485ed17 --- /dev/null +++ b/docs/i18n/en/docusaurus-theme-classic/navbar.json @@ -0,0 +1,30 @@ +{ + "title": { + "message": "Audius", + "description": "The title in the navbar" + }, + "logo.alt": { + "message": "Audius Logo", + "description": "The alt text of navbar logo" + }, + "item.label.Learn": { + "message": "Learn", + "description": "Navbar item with label Learn" + }, + "item.label.Developers": { + "message": "Developers", + "description": "Navbar item with label Developers" + }, + "item.label.Staking": { + "message": "Staking", + "description": "Navbar item with label Staking" + }, + "item.label.Distributors": { + "message": "Distributors", + "description": "Navbar item with label Distributors" + }, + "item.label.Reference": { + "message": "Reference", + "description": "Navbar item with label Reference" + } +} diff --git a/docs/sidebars.js b/docs/sidebars.js index 89d05ea0d08..35497c82ea8 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -84,18 +84,18 @@ module.exports = { { type: 'category', label: 'Specification', - items: ['distributors/specification/overview', 'distributors/specification/ern3'], + items: ['distributors/specification/overview', 'distributors/specification/ern3', 'distributors/specification/ern4'], + collapsed: false, + }, + { + type: 'category', + label: 'Self Serve', + items: [ + 'distributors/self-serve/overview', + 'distributors/self-serve/run-a-ddex-server', + ], collapsed: false, }, - // { - // type: 'category', - // label: 'Run a DDEX Server', - // items: [ - // 'distributors/run-a-server/overview', - // 'distributors/run-a-server/run-a-ddex-server', - // ], - // collapsed: false, - // }, ], node_operators: [ diff --git a/docs/src/css/custom.css b/docs/src/css/custom.css index 05ef6e7ef31..e1f5403a95f 100644 --- a/docs/src/css/custom.css +++ b/docs/src/css/custom.css @@ -22,7 +22,8 @@ footer { --ifm-color-primary-light: var(--secondary-light-1); --ifm-color-primary-lighter: var(--secondary-light-2); --ifm-color-primary-lightest: var(--neutral-light-4); - --ifm-code-font-size: 95%; + --ifm-code-font-size: 75%; + --ifm-code-font-weight: 600; --ifm-spacing-horizontal: 1em; --ifm-font-family-base: 'Avenir Next LT Pro', system-ui, -apple-system, Segoe UI, Roboto, Ubuntu, Cantarell, Noto Sans, sans-serif, BlinkMacSystemFont, 'Segoe UI', Helvetica, Arial, sans-serif, @@ -31,7 +32,8 @@ footer { --ifm-font-color-base: var(--neutral-dark-3); --ifm-font-weight-base: 500; --ifm-footer-background-color: #35364f !important; - --ifm-code-background: var(--neutral-light-9); + --ifm-code-background: var(--neutral-light-10); + --ifm-code-padding-horizontal: 2px; --docsearch-searchbox-background: var(--white); --ifm-color-danger-contrast-background: var(--accent-red); --ifm-color-danger-contrast-foreground: var(--static-white); @@ -162,6 +164,11 @@ footer .text--center { /* Customized CSS Starts Here */ /* ///////////////////////////////////////////////////////////////////////// */ +code { + font-weight: 600; + color: var(--neutral-dark-1); +} + /* Home Page customized css */ img.welcomeBanner { @@ -316,3 +323,9 @@ html[data-theme='dark'] .navbar__items > a:nth-child(1):hover { html[data-theme='dark'] .tabs__item--active { background-color: #00000080; } + +/* list elements */ + +.markdown li { + margin-bottom: 12px; +} \ No newline at end of file From e22dd48bd3e9c7480c7f0a423b94eee8bedcef11 Mon Sep 17 00:00:00 2001 From: Raymond Jacobson Date: Thu, 4 Apr 2024 16:50:58 -0700 Subject: [PATCH 03/12] [DVRL-24] Keep top tab highlighted (#8033) --- docs/docs/distributors/self-serve/run-a-ddex-server.mdx | 3 ++- docs/docusaurus.config.js | 9 ++++++--- 2 files changed, 8 insertions(+), 4 deletions(-) diff --git a/docs/docs/distributors/self-serve/run-a-ddex-server.mdx b/docs/docs/distributors/self-serve/run-a-ddex-server.mdx index 9153ed698ef..d1451bb11c8 100644 --- a/docs/docs/distributors/self-serve/run-a-ddex-server.mdx +++ b/docs/docs/distributors/self-serve/run-a-ddex-server.mdx @@ -18,10 +18,11 @@ Check back soon for updates on how to run and operate own DDEX Ingestion Server. ## Instructions -1. Provision a new machine following. We recommend: +1. Provision a new machine. We recommend: - Ubuntu - 8 CPUs - 16 to 32GB Memory + - 256 GB storage 2. Visit [audius-docker-compose](https://github.com/AudiusProject/audius-docker-compose) and run the install script to set up your Audius environment on your provisioned machine. diff --git a/docs/docusaurus.config.js b/docs/docusaurus.config.js index dc2e6f839eb..867ba0c1d4c 100644 --- a/docs/docusaurus.config.js +++ b/docs/docusaurus.config.js @@ -44,9 +44,7 @@ const config = { path: 'docs', routeBasePath: '/', sidebarPath: './sidebars.js', - // Please change this to your repo. - // Remove this to remove the "edit this page" links. - editUrl: 'https://github.com/AudiusProject/docs.audius.org/', + editUrl: 'https://github.com/AudiusProject/audius-protocol/tree/main/docs', }, theme: { customCss: './src/css/custom.css', @@ -76,26 +74,31 @@ const config = { label: 'Learn', to: '/', position: 'right', + activeBasePath: 'learn' }, { label: 'Developers', to: '/developers/introduction/overview', position: 'right', + activeBasePath: 'developers' }, { label: 'Staking', to: '/node-operator/overview', position: 'right', + activeBasePath: 'staking' }, { label: 'Distributors', to: '/distributors/introduction/overview', position: 'right', + activeBasePath: 'distributors' }, { label: 'Reference', to: '/reference/overview', position: 'right', + activeBasePath: 'reference' }, { 'aria-label': 'Discord', From d332701f35493241dcb44af648f0a5db727bdfe1 Mon Sep 17 00:00:00 2001 From: Sam Gutentag <1404219+samgutentag@users.noreply.github.com> Date: Fri, 5 Apr 2024 16:30:02 -0700 Subject: [PATCH 04/12] formatting fixes --- docs/.vscode/spellright.dict | 1 + docs/README.md | 14 +++++------ .../distributors/introduction/overview.mdx | 9 ++++---- .../docs/distributors/self-serve/overview.mdx | 5 ++-- .../self-serve/run-a-ddex-server.mdx | 23 ++++++++++--------- docs/docs/distributors/specification/ern3.mdx | 18 ++++++++++----- docs/docs/distributors/specification/ern4.mdx | 10 +++++++- 7 files changed, 49 insertions(+), 31 deletions(-) diff --git a/docs/.vscode/spellright.dict b/docs/.vscode/spellright.dict index c43da3e57cb..9e98df4c00c 100644 --- a/docs/.vscode/spellright.dict +++ b/docs/.vscode/spellright.dict @@ -7,6 +7,7 @@ delegater delegaters docusaurus erc +ern ern3 ern4 esque diff --git a/docs/README.md b/docs/README.md index c80a3a69c0f..45f716c0c17 100644 --- a/docs/README.md +++ b/docs/README.md @@ -2,7 +2,7 @@ ## Dev -``` +```sh npm install npm run prepare:translations npm start @@ -10,13 +10,13 @@ npm start To develop on cloudflare pages and test the whole stack, run: -``` +```sh npm run pages:dev ``` ## Build -``` +```sh npm run build ``` @@ -26,16 +26,16 @@ Running the following commands will create a public test site to view your chang To deploy to docs.audius.org, ensure the commands are run from the `main` branch. -``` +```sh npm run build npm run pages:deploy ``` ## Translate -``` +```sh npm run prepare:translations ``` -This will write translations to the i18n folder. -If you modify markdown files while running the local dev server, you will need to prepare the translations as /i18n/en is the default entrypoint. +This will write translations to the i18n folder. If you modify markdown files while running the +local dev server, you will need to prepare the translations as /i18n/en is the default entrypoint. diff --git a/docs/docs/distributors/introduction/overview.mdx b/docs/docs/distributors/introduction/overview.mdx index bea3c481b03..6b9b813a7b3 100644 --- a/docs/docs/distributors/introduction/overview.mdx +++ b/docs/docs/distributors/introduction/overview.mdx @@ -17,7 +17,8 @@ Visit [ddex.audius.co](https://ddex.audius.co) and check the Audius supports bulk content ingestion via the DDEX standard. -If you're looking to build your own ingestion tooling, get started with the [Audius SDK](../../developers/sdk/overview). +If you're looking to build your own ingestion tooling, get started with the +[Audius SDK](/developers/sdk/overview). ## What is DDEX @@ -43,6 +44,6 @@ supply chain more efficiently by: All DDEX ingestion code & libraries are open source and available on [GitHub](https://github.com/AudiusProject/audius-protocol/tree/main/packages/ddex). -You may clone and self-operate your own Audius compatible DDEX ingestion server, which provides a web -interface to deliver files, manage uploads, and track success. Under the hood, DDEX ingestion uses -the [Audius SDK](../../developers/sdk/overview) to process and upload tracks. +You may clone and self-operate your own Audius compatible DDEX ingestion server, which provides a +web interface to deliver files, manage uploads, and track success. Under the hood, DDEX ingestion +uses the [Audius SDK](/developers/sdk/overview) to process and upload tracks. diff --git a/docs/docs/distributors/self-serve/overview.mdx b/docs/docs/distributors/self-serve/overview.mdx index ab9df4188e4..552346e02c0 100644 --- a/docs/docs/distributors/self-serve/overview.mdx +++ b/docs/docs/distributors/self-serve/overview.mdx @@ -10,10 +10,11 @@ import useBaseUrl from '@docusaurus/useBaseUrl' --- -Content can be ingested into the Audius network by directly operating your own DDEX ingestion server. +Content can be ingested into the Audius network by directly operating your own DDEX ingestion +server. :::info More details soon -::: \ No newline at end of file +::: diff --git a/docs/docs/distributors/self-serve/run-a-ddex-server.mdx b/docs/docs/distributors/self-serve/run-a-ddex-server.mdx index d1451bb11c8..49fc639ec9e 100644 --- a/docs/docs/distributors/self-serve/run-a-ddex-server.mdx +++ b/docs/docs/distributors/self-serve/run-a-ddex-server.mdx @@ -18,17 +18,18 @@ Check back soon for updates on how to run and operate own DDEX Ingestion Server. ## Instructions -1. Provision a new machine. We recommend: - - Ubuntu - - 8 CPUs - - 16 to 32GB Memory - - 256 GB storage +1. Provision a new machine following. We recommend: -2. Visit [audius-docker-compose](https://github.com/AudiusProject/audius-docker-compose) and -run the install script to set up your Audius environment on your provisioned machine. +- Ubuntu +- 8 CPUs +- 16 to 32GB Memory -3. Follow the instructions in the [audius-protocol](https://github.com/AudiusProject/audius-protocol/tree/main/packages/ddex) -repository to set the appropriate environment variables +2. Visit [audius-docker-compose](https://github.com/AudiusProject/audius-docker-compose) and run the + install script to set up your Audius environment on your provisioned machine. + +3. Follow the instructions in the + [audius-protocol](https://github.com/AudiusProject/audius-protocol/tree/main/packages/ddex) + repository to set the appropriate environment variables 4. Start the DDEX Ingestion Server @@ -36,5 +37,5 @@ repository to set the appropriate environment variables audius-cli launch ddex ``` -Your server will now be available at localhost:80 and is exposed via self-signed SSL on :443 if `DDEX_URL` -is set. +Your server will now be available at localhost:80 and is exposed via self-signed SSL on :443 if +`DDEX_URL` is set. diff --git a/docs/docs/distributors/specification/ern3.mdx b/docs/docs/distributors/specification/ern3.mdx index 5dc1025b69e..0f45db762be 100644 --- a/docs/docs/distributors/specification/ern3.mdx +++ b/docs/docs/distributors/specification/ern3.mdx @@ -8,14 +8,21 @@ description: Support for ERN3 import useBaseUrl from '@docusaurus/useBaseUrl' -# ERN3 +:::info Further Reading -[DDEX ERN3 Knowledge Base](https://kb.ddex.net/implementing-each-standard/electronic-release-notification-message-suite-(ern)/ern-3-explained/) +Checkout the +[DDEX ERN3 Knowledge Base]() +for more information. -The following `Deal` types are supported for distribution to Audius. `Deal` types provided outside of -the provided list will be ignored. +::: + +The following `Deal` types are supported for distribution to Audius. `Deal` types provided outside +of the provided list will be ignored. -If your use case extends beyond the supported `Deal` types outlined below, please contact `support@audius.co`. +If your use case extends beyond the supported `Deal` types outlined below, please contact +`support@audius.co`. + +--- ## Tracks @@ -413,4 +420,3 @@ If you can download it, you can stream it. ``` - diff --git a/docs/docs/distributors/specification/ern4.mdx b/docs/docs/distributors/specification/ern4.mdx index b0acbad5ac2..b76df1e412c 100644 --- a/docs/docs/distributors/specification/ern4.mdx +++ b/docs/docs/distributors/specification/ern4.mdx @@ -6,4 +6,12 @@ sidebar_label: ERN4 🚧 description: Support for ERN4 --- -Coming Soon \ No newline at end of file +:::info Coming Soon + +Support for ERN4 is coming coming soon. + +Checkout the +[DDEX ERN4 Knowledge Base]() +for information in the meantime. + +::: From 2a603ed0c10ea06103f9172b9a9e017c787a3c5d Mon Sep 17 00:00:00 2001 From: Sam Gutentag <1404219+samgutentag@users.noreply.github.com> Date: Fri, 5 Apr 2024 16:30:13 -0700 Subject: [PATCH 05/12] added metadata field mappings --- .../distributors/specification/overview.mdx | 305 ++++++++++++++++-- 1 file changed, 287 insertions(+), 18 deletions(-) diff --git a/docs/docs/distributors/specification/overview.mdx b/docs/docs/distributors/specification/overview.mdx index 54c7caa30eb..d0d458ba495 100644 --- a/docs/docs/distributors/specification/overview.mdx +++ b/docs/docs/distributors/specification/overview.mdx @@ -12,18 +12,20 @@ import useBaseUrl from '@docusaurus/useBaseUrl' :::info Delivery processing -[TikiLabs](https://tikilabs.com) is a facilitator of distributing DDEX directly to the Audius Protocol -For inquiries or support, reach out at support@audius.co. +[TikiLabs](https://tikilabs.com) is a facilitator of distributing DDEX directly to the Audius +Protocol For inquiries or support, reach out at support@audius.co. ::: -- ERN3 is the preferred DDEX specification for bulk ingestion into Audius. See the [ERN3 details](./ern3) for more details around submission choreography. +- ERN3 is the preferred DDEX specification for bulk ingestion into Audius. See the + [ERN3 details](./ern3) for more details around submission choreography. - Audius only accepts price information using absolute prices (e.g. via `WholesalePricePerUnit`). Price codes will be ignored (e.g. `PriceType`). - Audius also does not support `ValidityPeriod` `EndDate`s. This includes using `EndDate` to specify multiple `ValidityPeriod`s with different prices. We can only parse 1 `ValidityPeriod` `StartDate`. -- Audius currently only accepts the `Worldwide` `TerritoryCode`. Territory support for controlled streaming is coming soon! 🌎 +- Audius currently only accepts the `Worldwide` `TerritoryCode`. Territory support for controlled + streaming is coming soon! 🌎 - `NonInteractiveStream` is not supported. - A `ReleaseDeal` is required with a `DealReleaseReference` to each track on an album. - A `ReleaseDeal` is not required with a `DealReleaseReference` to an album release. If an album @@ -38,29 +40,296 @@ Please note that exact DDEX fields will depend on the specific ERN version. ::: -### Required +--- + +### Required Fields + +The following fields are required by the Audius SDK and map to DDEX fields in a cascade. + +#### releaseDate + +1. `/DealList/ReleaseDeal/Deal/ValidityPeriod/StartDate` +2. `/ReleaseList/Release/ReleaseDetailsByTerritory[TerritoryCode="Worldwide"]/ReleaseDate` +3. `/ReleaseList/Release/GlobalOriginalReleaseDate` + +#### genre + +1. `/ReleaseList/Release/ReleaseDetailsByTerritory[TerritoryCode="Worldwide"]/Genre/SubGenre` +2. `/ReleaseList/Release/ReleaseDetailsByTerritory[TerritoryCode="Worldwide"]/Genre/GenreText` +3. (only for tracks) + `/ResourceList/SoundRecording/SoundRecordingDetailsByTerritory[TerritoryCode="Worldwide"]/Genre/SubGenre` +4. (only for tracks) + `/ResourceList/SoundRecording/SoundRecordingDetailsByTerritory[TerritoryCode="Worldwide"]/Genre/GenreText` + +#### coverArtFile + +the `coverArtFile` maps to two DDEX Fields + +- `/ResourceList/Image/ImageDetailsByTerritory[TerritoryCode="Worldwide"]/TechnicalImageDetails/File/FilePath` +- `/ResourceList/Image/ImageDetailsByTerritory[TerritoryCode="Worldwide"]/TechnicalImageDetails/File/FileName` + +:::info + +Not technically an Audius SDK metadata field, but uploaded as part of the track/album. note that +this DDEX field is a relative path to the file within the delivery + +::: + +#### userId + +1. same as artists (next row below): checks each artist name (in order) against Audius database of + OAuthed display names, and uses the first match + +:::info + +not technically an Audius SDK metadata field, but uploaded as part of the track/album + +::: + +--- + +### Optional Fields + +The following fields are optional, and will map to the listed DDEX fields. + +#### artists + +1. (only for tracks) + `/ResourceList/SoundRecording/SoundRecordingDetailsByTerritory[TerritoryCode="Worldwide"]/DisplayArtist` +2. `/ReleaseList/Release/ReleaseDetailsByTerritory[TerritoryCode="Worldwide"]/DisplayArtist` + +:::info + +we use the `/PartyName/FullName` child element as the artist’s name and the `SequenceNumber` +attribute to preserve order + +::: + +#### ddexReleaseIds + +1. `/ReleaseList/Release/ReleaseId` + +:::info + +from this element, we parse+preserve many IDs (children elements): `PartyId`, `CatalogNumber`, +`ICPN`, `GRid`, `ISAN`, `ISBN`, `ISMN`, `ISRC`, `ISSN`, `ISTC`, `ISWC`, `MWLI`, `SICI`, and +`ProprietaryId` + +::: + +#### copyrightLine + +1. (only for tracks) + `/ResourceList/SoundRecording/SoundRecordingDetailsByTerritory[TerritoryCode="Worldwide"]/CLine` +2. `/ReleaseList/Release/ReleaseDetailsByTerritory[TerritoryCode="Worldwide"]/CLine` +3. `/ReleaseList/Release/CLine` + +:::info + +only used if both year AND text are non-empty. the child elements that are parsed are: `Year` and +`CLineText` + +::: + +#### producerCopyrightLine + +1. (only for tracks) + `/ResourceList/SoundRecording/SoundRecordingDetailsByTerritory[TerritoryCode="Worldwide"]/PLine` +2. `/ReleaseList/Release/ReleaseDetailsByTerritory[TerritoryCode="Worldwide"]/PLine` +3. `/ReleaseList/Release/PLine` + +:::info + +only used if both year AND text are non-empty. the child elements that are parsed are: `Year` and +`PLineText` + +::: + +#### parentalWarningType + +1. (only for tracks) + `/ResourceList/SoundRecording/SoundRecordingDetailsByTerritory[TerritoryCode="Worldwide"]/ParentalWarningType` +2. `/ReleaseList/Release/ReleaseDetailsByTerritory[TerritoryCode="Worldwide"]/ParentalWarningType` + +#### description + +The DDEX standard includes a `MarketingComments` field that is rarely used, but is available. + +--- + +### Unused Fields + +The following Audius SDK Fields are not used by DDEX and have no mapping. + +#### license + +:::info + +we don’t know which DDEX field to use for this, but it seems like something that would be +communicated somewhere + +::: + +#### mood and tags + +:::info + +never passed to Audius SDK because DDEX doesn’t provide these and likely never will + +::: +#### child elements of `/ReleaseList/Release/` -| Audius | DDEX | Notes | -| ------------------------------------------------------------------ | ----------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| releaseDate | /ReleaseList/Release/GlobalOriginalReleaseDate | TODO: This is apparently deprecated. Probably needs to change to use a date from DealList | -| duration | /ResourceList/SoundRecording/Duration | Parsed as ISO 8601. Falls back to /ReleaseList/Release/Duration from the release with a matching ResourceReference | +The following child elements are parsed and stored in the separate DDEX server, but not stored in +Audius and not used anywhere: +- `ReferenceTitle/TitleText` +- `ReferenceTitle/SubTitle` + +#### child elements of `/ReleaseList/Release/ReleaseDetailsByTerritory[TerritoryCode="Worldwide"]/` + +The following child elements are parsed and stored in the separate DDEX server, but not stored in +Audius and not used anywhere: + +- `Title[@TitleType='DisplayTitle']/TitleText` (used in albums/EPs but not single tracks) +- `Title[@TitleType='DisplayTitle']/SubTitle` +- `Title[@TitleType='FormalTitle']/TitleText` +- `Title[@TitleType='FormalTitle']/SubTitle ` + +#### child elements of `/ReleaseList/Release/ReleaseDetailsByTerritory[TerritoryCode="Worldwide"]/ResourceGroup/` + +The following child elements are parsed and stored in the separate DDEX server, but not stored in +Audius and not used anywhere: + +- `SequenceNumber` +- `ResourceGroupContentItem/ResourceType` +- `ResourceGroupContentItem/ReleaseResourceReference` +- `ResourceGroupContentItem/IsInstantGratificationResource` + +--- + +## Track Metadata Mapping + +### Required Fields + +#### title + +1. `/ResourceList/SoundRecording/ReferenceTitle/TitleText` + +:::info + +Subtitle is currently ignored/unused, which likely needs to change (perhaps make title be +`“ - <subtitle>.”` also note that DDEX communicates additional titles (eg, +`<Title TitleType=”DisplayTitle”>` and `<Title TitleType=”FormalTitle”>`) in the both the +SoundRecording and release. we store these in the separate DDEX server but not in the Audius network + +::: + +#### trackFile + +the `trackFile` maps to two DDEX Fields + +- `/ResourceList/SoundRecording/SoundDetailsByTerritory[TerritoryCode="Worldwide"]/TechnicalSoundRecordingDetails/File/FilePath` +- `/ResourceList/SoundRecording/SoundDetailsByTerritory[TerritoryCode="Worldwide"]/TechnicalSoundRecordingDetails/File/FileName` + +:::info + +the actual audio file. not technically an Audius SDK metadata field, but uploaded in the same SDK +function. note that this DDEX field is a relative path to the file within the delivery + +::: + +--- ### Optional +#### isrc + +1. `/ResourceList/SoundRecording/SoundRecordingId/ISRC` -| Audius | DDEX | Notes | -| ------------------------------------------------------------------ | ----------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| releaseDate | /ReleaseList/Release/GlobalOriginalReleaseDate | TODO: This is apparently deprecated. Probably needs to change to use a date from DealList | -| duration | /ResourceList/SoundRecording/Duration | Parsed as ISO 8601. Falls back to /ReleaseList/Release/Duration from the release with a matching ResourceReference | +#### resourceContributors +1. `/ResourceList/SoundRecording/SoundDetailsByTerritory[TerritoryCode="Worldwide"]/ResourceContributor` -### Unused +:::info +the following children elements are parsed and stored in Audius: `PartyName`/`FullName`, +`SequenceNumber`, and `ResourceContributorRole` + +::: + +#### indirectResourceContributors + +1. `/ResourceList/SoundRecording/SoundDetailsByTerritory[TerritoryCode="Worldwide"]/IndirectResourceContributor` + +:::info + +the following children elements are parsed and stored in Audius: `PartyName`/`FullName`, +`SequenceNumber`, and `IndirectResourceContributorRole` + +::: -| Audius | DDEX | Notes | -| ------------------------------------------------------------------ | ----------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| releaseDate | /ReleaseList/Release/GlobalOriginalReleaseDate | TODO: This is apparently deprecated. Probably needs to change to use a date from DealList | -| duration | /ResourceList/SoundRecording/Duration | Parsed as ISO 8601. Falls back to /ReleaseList/Release/Duration from the release with a matching ResourceReference | +#### rightsController +1. `/ResourceList/SoundRecording/SoundDetailsByTerritory[TerritoryCode="Worldwide"]/RightsController` + +:::info + +the following children elements are parsed and stored in Audius: `PartyName`/`FullName`, +`RightsShareUnknown`, and `RightsControllerRole` + +::: + +#### previewStartSeconds + +1. `/ResourceList/SoundRecording/SoundDetailsByTerritory[TerritoryCode="Worldwide"]/TechnicalSoundRecordingDetails/PreviewDetails/StartPoint` +2. only when + `/ResourceList/SoundRecording/SoundDetailsByTerritory[TerritoryCode="Worldwide"]/TechnicalSoundRecordingDetails/IsPreview` + is true + +:::info + +Preview length is 30 seconds starting at the `previewStartSeconds` into the track’s audio, even if a +longer or shorter duration is given. does not support using an external file for the preview + +::: + +--- + +## Album Metadata Mapping + +### Required + +#### albumName + +1. `/ReleaseList/Release/ReleaseDetailsByTerritory[TerritoryCode="Worldwide"]/Title[@TitleType='DisplayTitle']/TitleText` + +:::info + +subtitle is currently ignored/unused, which likely needs to change (perhaps make title be +`“<title> - <subtitle>.”` the same element but with `TitleType=’FormalTitle’`, as well as a +`<ReferenceTitle>` element, are stored in the separate DDEX server but not in the Audius network + +::: + +#### trackMetadatas + +1. each `/ReleaseList/Release/` except the release with the attribute `IsMainRelease="true"` + +:::info + +metadata about each track in the album. not technically an Audius SDK metadata field, but uploaded +as part of the album + +::: + +#### trackFiles + +1. each `/ReleaseList/Release/` except the release with the attribute `IsMainRelease="true"` + +:::info + +array of audio files which the album is comprised of. not technically an Audius SDK metadata field, +but uploaded as part of the album + +::: From 047cc986fd62fce9ebce4abeaefd04322df4815e Mon Sep 17 00:00:00 2001 From: Sam Gutentag <1404219+samgutentag@users.noreply.github.com> Date: Fri, 5 Apr 2024 16:59:22 -0700 Subject: [PATCH 06/12] split metadata mapping to unique page --- .../distributors/specification/metadata.mdx | 367 ++++++++++++++++++ .../distributors/specification/overview.mdx | 304 +-------------- docs/sidebars.js | 12 +- 3 files changed, 375 insertions(+), 308 deletions(-) create mode 100644 docs/docs/distributors/specification/metadata.mdx diff --git a/docs/docs/distributors/specification/metadata.mdx b/docs/docs/distributors/specification/metadata.mdx new file mode 100644 index 00000000000..f91f50a49f5 --- /dev/null +++ b/docs/docs/distributors/specification/metadata.mdx @@ -0,0 +1,367 @@ +--- +id: metadata +title: Metadata Mapping +pagination_label: Metadata Mapping +sidebar_label: Metadata Mapping +description: Audius SDK to DDEX Metadata Mapping +--- + +import useBaseUrl from '@docusaurus/useBaseUrl' + +:::info The following is provided based on ERN3.8 + +Please note that exact DDEX fields will depend on the specific ERN version. + +::: + +--- + +## Metadata Mapping + +### Required Fields + +The following metadata fields are required for content to be listed on Audius and are examined and +pulled from a DDEX delivery in cascading precedence. + +#### releaseDate + +1. `/DealList/ReleaseDeal/Deal/ValidityPeriod/StartDate` +2. `/ReleaseList/Release/ReleaseDetailsByTerritory[TerritoryCode="Worldwide"]/ReleaseDate` +3. `/ReleaseList/Release/GlobalOriginalReleaseDate` + +#### coverArtFile + +the `coverArtFile` maps to two DDEX Fields + +- `/ResourceList/Image/ImageDetailsByTerritory[TerritoryCode="Worldwide"]/TechnicalImageDetails/File/FilePath` +- `/ResourceList/Image/ImageDetailsByTerritory[TerritoryCode="Worldwide"]/TechnicalImageDetails/File/FileName` + +:::info + +Not technically an Audius SDK metadata field, but uploaded as part of the track/album. note that +this DDEX field is a relative path to the file within the delivery + +::: + +#### userId + +1. same as artists (next row below): checks each artist name (in order) against Audius database of + OAuthed display names, and uses the first match + +:::info + +not technically an Audius SDK metadata field, but uploaded as part of the track/album + +::: + +--- + +### Optional Fields + +The following fields are optional for content to be listed on Audius and are examined and pulled +from a DDEX delivery in cascading precedence. + +#### ddexReleaseIds + +1. `/ReleaseList/Release/ReleaseId` + +:::info + +from this element, we parse+preserve many IDs (children elements): `PartyId`, `CatalogNumber`, +`ICPN`, `GRid`, `ISAN`, `ISBN`, `ISMN`, `ISRC`, `ISSN`, `ISTC`, `ISWC`, `MWLI`, `SICI`, and +`ProprietaryId` + +::: + +#### description + +The DDEX standard includes a `MarketingComments` field that is rarely used, but is available. + +--- + +### Unused Fields + +The following Audius SDK Fields are not used by DDEX and have no mapping. + +#### license + +:::info + +we don’t know which DDEX field to use for this, but it seems like something that would be +communicated somewhere + +::: + +#### mood and tags + +:::info + +never passed to Audius SDK because DDEX doesn’t provide these and likely never will + +::: + +#### child elements of `/ReleaseList/Release/` + +The following child elements are parsed and stored in the separate DDEX server, but not stored in +Audius and not used anywhere: + +- `ReferenceTitle/TitleText` +- `ReferenceTitle/SubTitle` + +#### child elements of `/ReleaseList/Release/ReleaseDetailsByTerritory[TerritoryCode="Worldwide"]/` + +The following child elements are parsed and stored in the separate DDEX server, but not stored in +Audius and not used anywhere: + +- `Title[@TitleType='DisplayTitle']/TitleText` (used in albums/EPs but not single tracks) +- `Title[@TitleType='DisplayTitle']/SubTitle` +- `Title[@TitleType='FormalTitle']/TitleText` +- `Title[@TitleType='FormalTitle']/SubTitle ` + +#### child elements of `/ReleaseList/Release/ReleaseDetailsByTerritory[TerritoryCode="Worldwide"]/ResourceGroup/` + +The following child elements are parsed and stored in the separate DDEX server, but not stored in +Audius and not used anywhere: + +- `SequenceNumber` +- `ResourceGroupContentItem/ResourceType` +- `ResourceGroupContentItem/ReleaseResourceReference` +- `ResourceGroupContentItem/IsInstantGratificationResource` + +--- + +## Track Metadata Mapping + +### Required Fields + +The following fields are required for content to be listed on Audius and are examined and pulled +from a DDEX delivery in cascading precedence. + +#### genre + +1. `/ReleaseList/Release/ReleaseDetailsByTerritory[TerritoryCode="Worldwide"]/Genre/SubGenre` +2. `/ReleaseList/Release/ReleaseDetailsByTerritory[TerritoryCode="Worldwide"]/Genre/GenreText` +3. `/ResourceList/SoundRecording/SoundRecordingDetailsByTerritory[TerritoryCode="Worldwide"]/Genre/SubGenre` +4. `/ResourceList/SoundRecording/SoundRecordingDetailsByTerritory[TerritoryCode="Worldwide"]/Genre/GenreText` + +#### title + +1. `/ResourceList/SoundRecording/ReferenceTitle/TitleText` + +:::info + +Subtitle is currently ignored/unused, which likely needs to change (perhaps make title be +`“<title> - <subtitle>.”` also note that DDEX communicates additional titles (eg, +`<Title TitleType=”DisplayTitle”>` and `<Title TitleType=”FormalTitle”>`) in the both the +SoundRecording and release. we store these in the separate DDEX server but not in the Audius network + +::: + +#### trackFile + +the `trackFile` maps to two DDEX Fields + +- `/ResourceList/SoundRecording/SoundDetailsByTerritory[TerritoryCode="Worldwide"]/TechnicalSoundRecordingDetails/File/FilePath` +- `/ResourceList/SoundRecording/SoundDetailsByTerritory[TerritoryCode="Worldwide"]/TechnicalSoundRecordingDetails/File/FileName` + +:::info + +the actual audio file. not technically an Audius SDK metadata field, but uploaded in the same SDK +function. note that this DDEX field is a relative path to the file within the delivery + +::: + +--- + +### Optional + +The following fields are optional for content to be listed on Audius and are examined and pulled +from a DDEX delivery in cascading precedence. + +#### artists + +1. `/ResourceList/SoundRecording/SoundRecordingDetailsByTerritory[TerritoryCode="Worldwide"]/DisplayArtist` +2. `/ReleaseList/Release/ReleaseDetailsByTerritory[TerritoryCode="Worldwide"]/DisplayArtist` + +:::info + +we use the `/PartyName/FullName` child element as the artist’s name and the `SequenceNumber` +attribute to preserve order + +::: + +#### copyrightLine + +1. `/ResourceList/SoundRecording/SoundRecordingDetailsByTerritory[TerritoryCode="Worldwide"]/CLine` +2. `/ReleaseList/Release/ReleaseDetailsByTerritory[TerritoryCode="Worldwide"]/CLine` +3. `/ReleaseList/Release/CLine` + +:::info + +only used if both year AND text are non-empty. the child elements that are parsed are: `Year` and +`CLineText` + +::: + +#### producerCopyrightLine + +1. `/ResourceList/SoundRecording/SoundRecordingDetailsByTerritory[TerritoryCode="Worldwide"]/PLine` +2. `/ReleaseList/Release/ReleaseDetailsByTerritory[TerritoryCode="Worldwide"]/PLine` +3. `/ReleaseList/Release/PLine` + +:::info + +only used if both year AND text are non-empty. the child elements that are parsed are: `Year` and +`PLineText` + +::: + +#### parentalWarningType + +1. `/ResourceList/SoundRecording/SoundRecordingDetailsByTerritory[TerritoryCode="Worldwide"]/ParentalWarningType` +2. `/ReleaseList/Release/ReleaseDetailsByTerritory[TerritoryCode="Worldwide"]/ParentalWarningType` + +#### isrc + +1. `/ResourceList/SoundRecording/SoundRecordingId/ISRC` + +#### resourceContributors + +1. `/ResourceList/SoundRecording/SoundDetailsByTerritory[TerritoryCode="Worldwide"]/ResourceContributor` + +:::info + +the following children elements are parsed and stored in Audius: `PartyName`/`FullName`, +`SequenceNumber`, and `ResourceContributorRole` + +::: + +#### indirectResourceContributors + +1. `/ResourceList/SoundRecording/SoundDetailsByTerritory[TerritoryCode="Worldwide"]/IndirectResourceContributor` + +:::info + +the following children elements are parsed and stored in Audius: `PartyName`/`FullName`, +`SequenceNumber`, and `IndirectResourceContributorRole` + +::: + +#### rightsController + +1. `/ResourceList/SoundRecording/SoundDetailsByTerritory[TerritoryCode="Worldwide"]/RightsController` + +:::info + +the following children elements are parsed and stored in Audius: `PartyName`/`FullName`, +`RightsShareUnknown`, and `RightsControllerRole` + +::: + +#### previewStartSeconds + +1. `/ResourceList/SoundRecording/SoundDetailsByTerritory[TerritoryCode="Worldwide"]/TechnicalSoundRecordingDetails/PreviewDetails/StartPoint` +2. only when + `/ResourceList/SoundRecording/SoundDetailsByTerritory[TerritoryCode="Worldwide"]/TechnicalSoundRecordingDetails/IsPreview` + is true + +:::info + +Preview length is 30 seconds starting at the `previewStartSeconds` into the track’s audio, even if a +longer or shorter duration is given. does not support using an external file for the preview + +::: + +--- + +## Album Metadata Mapping + +### Required + +The following fields are required for content to be listed on Audius and are examined and pulled +from a DDEX delivery in cascading precedence. + +#### albumName + +1. `/ReleaseList/Release/ReleaseDetailsByTerritory[TerritoryCode="Worldwide"]/Title[@TitleType='DisplayTitle']/TitleText` + +:::info + +subtitle is currently ignored/unused, which likely needs to change (perhaps make title be +`“<title> - <subtitle>.”` the same element but with `TitleType=’FormalTitle’`, as well as a +`<ReferenceTitle>` element, are stored in the separate DDEX server but not in the Audius network + +::: + +#### genre + +1. `/ReleaseList/Release/ReleaseDetailsByTerritory[TerritoryCode="Worldwide"]/Genre/SubGenre` +2. `/ReleaseList/Release/ReleaseDetailsByTerritory[TerritoryCode="Worldwide"]/Genre/GenreText` + +#### trackMetadatas + +1. each `/ReleaseList/Release/` except the release with the attribute `IsMainRelease="true"` + +:::info + +metadata about each track in the album. not technically an Audius SDK metadata field, but uploaded +as part of the album + +::: + +#### trackFiles + +1. each `/ReleaseList/Release/` except the release with the attribute `IsMainRelease="true"` + +:::info + +array of audio files which the album is comprised of. not technically an Audius SDK metadata field, +but uploaded as part of the album + +::: + +--- + +### Optional + +The following fields are optional for content to be listed on Audius and are examined and pulled +from a DDEX delivery in cascading precedence. + +#### artists + +1. `/ReleaseList/Release/ReleaseDetailsByTerritory[TerritoryCode="Worldwide"]/DisplayArtist` + +:::info + +we use the `/PartyName/FullName` child element as the artist’s name and the `SequenceNumber` +attribute to preserve order + +::: + +#### copyrightLine + +1`/ReleaseList/Release/ReleaseDetailsByTerritory[TerritoryCode="Worldwide"]/CLine` 2. +`/ReleaseList/Release/CLine` + +:::info + +only used if both year AND text are non-empty. the child elements that are parsed are: `Year` and +`CLineText` + +::: + +#### producerCopyrightLine + +1. `/ReleaseList/Release/ReleaseDetailsByTerritory[TerritoryCode="Worldwide"]/PLine` +2. `/ReleaseList/Release/PLine` + +:::info + +only used if both year AND text are non-empty. the child elements that are parsed are: `Year` and +`PLineText` + +::: + +#### parentalWarningType + +1. `/ReleaseList/Release/ReleaseDetailsByTerritory[TerritoryCode="Worldwide"]/ParentalWarningType` diff --git a/docs/docs/distributors/specification/overview.mdx b/docs/docs/distributors/specification/overview.mdx index d0d458ba495..eedb2e08e5e 100644 --- a/docs/docs/distributors/specification/overview.mdx +++ b/docs/docs/distributors/specification/overview.mdx @@ -18,7 +18,7 @@ Protocol For inquiries or support, reach out at support@audius.co. ::: - ERN3 is the preferred DDEX specification for bulk ingestion into Audius. See the - [ERN3 details](./ern3) for more details around submission choreography. + [ERN3 details](/distributors/specification/ern3) for more details around submission choreography. - Audius only accepts price information using absolute prices (e.g. via `WholesalePricePerUnit`). Price codes will be ignored (e.g. `PriceType`). - Audius also does not support `ValidityPeriod` `EndDate`s. This includes using `EndDate` to specify @@ -31,305 +31,3 @@ Protocol For inquiries or support, reach out at support@audius.co. - A `ReleaseDeal` is not required with a `DealReleaseReference` to an album release. If an album deal is not specified, the album defaults to being free to stream, but each of its tracks is configured according to the track’s `ReleaseDeal` `DealTerms`. - -## Metadata Mapping - -:::info The following is provided based on ERN3.8 - -Please note that exact DDEX fields will depend on the specific ERN version. - -::: - ---- - -### Required Fields - -The following fields are required by the Audius SDK and map to DDEX fields in a cascade. - -#### releaseDate - -1. `/DealList/ReleaseDeal/Deal/ValidityPeriod/StartDate` -2. `/ReleaseList/Release/ReleaseDetailsByTerritory[TerritoryCode="Worldwide"]/ReleaseDate` -3. `/ReleaseList/Release/GlobalOriginalReleaseDate` - -#### genre - -1. `/ReleaseList/Release/ReleaseDetailsByTerritory[TerritoryCode="Worldwide"]/Genre/SubGenre` -2. `/ReleaseList/Release/ReleaseDetailsByTerritory[TerritoryCode="Worldwide"]/Genre/GenreText` -3. (only for tracks) - `/ResourceList/SoundRecording/SoundRecordingDetailsByTerritory[TerritoryCode="Worldwide"]/Genre/SubGenre` -4. (only for tracks) - `/ResourceList/SoundRecording/SoundRecordingDetailsByTerritory[TerritoryCode="Worldwide"]/Genre/GenreText` - -#### coverArtFile - -the `coverArtFile` maps to two DDEX Fields - -- `/ResourceList/Image/ImageDetailsByTerritory[TerritoryCode="Worldwide"]/TechnicalImageDetails/File/FilePath` -- `/ResourceList/Image/ImageDetailsByTerritory[TerritoryCode="Worldwide"]/TechnicalImageDetails/File/FileName` - -:::info - -Not technically an Audius SDK metadata field, but uploaded as part of the track/album. note that -this DDEX field is a relative path to the file within the delivery - -::: - -#### userId - -1. same as artists (next row below): checks each artist name (in order) against Audius database of - OAuthed display names, and uses the first match - -:::info - -not technically an Audius SDK metadata field, but uploaded as part of the track/album - -::: - ---- - -### Optional Fields - -The following fields are optional, and will map to the listed DDEX fields. - -#### artists - -1. (only for tracks) - `/ResourceList/SoundRecording/SoundRecordingDetailsByTerritory[TerritoryCode="Worldwide"]/DisplayArtist` -2. `/ReleaseList/Release/ReleaseDetailsByTerritory[TerritoryCode="Worldwide"]/DisplayArtist` - -:::info - -we use the `/PartyName/FullName` child element as the artist’s name and the `SequenceNumber` -attribute to preserve order - -::: - -#### ddexReleaseIds - -1. `/ReleaseList/Release/ReleaseId` - -:::info - -from this element, we parse+preserve many IDs (children elements): `PartyId`, `CatalogNumber`, -`ICPN`, `GRid`, `ISAN`, `ISBN`, `ISMN`, `ISRC`, `ISSN`, `ISTC`, `ISWC`, `MWLI`, `SICI`, and -`ProprietaryId` - -::: - -#### copyrightLine - -1. (only for tracks) - `/ResourceList/SoundRecording/SoundRecordingDetailsByTerritory[TerritoryCode="Worldwide"]/CLine` -2. `/ReleaseList/Release/ReleaseDetailsByTerritory[TerritoryCode="Worldwide"]/CLine` -3. `/ReleaseList/Release/CLine` - -:::info - -only used if both year AND text are non-empty. the child elements that are parsed are: `Year` and -`CLineText` - -::: - -#### producerCopyrightLine - -1. (only for tracks) - `/ResourceList/SoundRecording/SoundRecordingDetailsByTerritory[TerritoryCode="Worldwide"]/PLine` -2. `/ReleaseList/Release/ReleaseDetailsByTerritory[TerritoryCode="Worldwide"]/PLine` -3. `/ReleaseList/Release/PLine` - -:::info - -only used if both year AND text are non-empty. the child elements that are parsed are: `Year` and -`PLineText` - -::: - -#### parentalWarningType - -1. (only for tracks) - `/ResourceList/SoundRecording/SoundRecordingDetailsByTerritory[TerritoryCode="Worldwide"]/ParentalWarningType` -2. `/ReleaseList/Release/ReleaseDetailsByTerritory[TerritoryCode="Worldwide"]/ParentalWarningType` - -#### description - -The DDEX standard includes a `MarketingComments` field that is rarely used, but is available. - ---- - -### Unused Fields - -The following Audius SDK Fields are not used by DDEX and have no mapping. - -#### license - -:::info - -we don’t know which DDEX field to use for this, but it seems like something that would be -communicated somewhere - -::: - -#### mood and tags - -:::info - -never passed to Audius SDK because DDEX doesn’t provide these and likely never will - -::: - -#### child elements of `/ReleaseList/Release/` - -The following child elements are parsed and stored in the separate DDEX server, but not stored in -Audius and not used anywhere: - -- `ReferenceTitle/TitleText` -- `ReferenceTitle/SubTitle` - -#### child elements of `/ReleaseList/Release/ReleaseDetailsByTerritory[TerritoryCode="Worldwide"]/` - -The following child elements are parsed and stored in the separate DDEX server, but not stored in -Audius and not used anywhere: - -- `Title[@TitleType='DisplayTitle']/TitleText` (used in albums/EPs but not single tracks) -- `Title[@TitleType='DisplayTitle']/SubTitle` -- `Title[@TitleType='FormalTitle']/TitleText` -- `Title[@TitleType='FormalTitle']/SubTitle ` - -#### child elements of `/ReleaseList/Release/ReleaseDetailsByTerritory[TerritoryCode="Worldwide"]/ResourceGroup/` - -The following child elements are parsed and stored in the separate DDEX server, but not stored in -Audius and not used anywhere: - -- `SequenceNumber` -- `ResourceGroupContentItem/ResourceType` -- `ResourceGroupContentItem/ReleaseResourceReference` -- `ResourceGroupContentItem/IsInstantGratificationResource` - ---- - -## Track Metadata Mapping - -### Required Fields - -#### title - -1. `/ResourceList/SoundRecording/ReferenceTitle/TitleText` - -:::info - -Subtitle is currently ignored/unused, which likely needs to change (perhaps make title be -`“<title> - <subtitle>.”` also note that DDEX communicates additional titles (eg, -`<Title TitleType=”DisplayTitle”>` and `<Title TitleType=”FormalTitle”>`) in the both the -SoundRecording and release. we store these in the separate DDEX server but not in the Audius network - -::: - -#### trackFile - -the `trackFile` maps to two DDEX Fields - -- `/ResourceList/SoundRecording/SoundDetailsByTerritory[TerritoryCode="Worldwide"]/TechnicalSoundRecordingDetails/File/FilePath` -- `/ResourceList/SoundRecording/SoundDetailsByTerritory[TerritoryCode="Worldwide"]/TechnicalSoundRecordingDetails/File/FileName` - -:::info - -the actual audio file. not technically an Audius SDK metadata field, but uploaded in the same SDK -function. note that this DDEX field is a relative path to the file within the delivery - -::: - ---- - -### Optional - -#### isrc - -1. `/ResourceList/SoundRecording/SoundRecordingId/ISRC` - -#### resourceContributors - -1. `/ResourceList/SoundRecording/SoundDetailsByTerritory[TerritoryCode="Worldwide"]/ResourceContributor` - -:::info - -the following children elements are parsed and stored in Audius: `PartyName`/`FullName`, -`SequenceNumber`, and `ResourceContributorRole` - -::: - -#### indirectResourceContributors - -1. `/ResourceList/SoundRecording/SoundDetailsByTerritory[TerritoryCode="Worldwide"]/IndirectResourceContributor` - -:::info - -the following children elements are parsed and stored in Audius: `PartyName`/`FullName`, -`SequenceNumber`, and `IndirectResourceContributorRole` - -::: - -#### rightsController - -1. `/ResourceList/SoundRecording/SoundDetailsByTerritory[TerritoryCode="Worldwide"]/RightsController` - -:::info - -the following children elements are parsed and stored in Audius: `PartyName`/`FullName`, -`RightsShareUnknown`, and `RightsControllerRole` - -::: - -#### previewStartSeconds - -1. `/ResourceList/SoundRecording/SoundDetailsByTerritory[TerritoryCode="Worldwide"]/TechnicalSoundRecordingDetails/PreviewDetails/StartPoint` -2. only when - `/ResourceList/SoundRecording/SoundDetailsByTerritory[TerritoryCode="Worldwide"]/TechnicalSoundRecordingDetails/IsPreview` - is true - -:::info - -Preview length is 30 seconds starting at the `previewStartSeconds` into the track’s audio, even if a -longer or shorter duration is given. does not support using an external file for the preview - -::: - ---- - -## Album Metadata Mapping - -### Required - -#### albumName - -1. `/ReleaseList/Release/ReleaseDetailsByTerritory[TerritoryCode="Worldwide"]/Title[@TitleType='DisplayTitle']/TitleText` - -:::info - -subtitle is currently ignored/unused, which likely needs to change (perhaps make title be -`“<title> - <subtitle>.”` the same element but with `TitleType=’FormalTitle’`, as well as a -`<ReferenceTitle>` element, are stored in the separate DDEX server but not in the Audius network - -::: - -#### trackMetadatas - -1. each `/ReleaseList/Release/` except the release with the attribute `IsMainRelease="true"` - -:::info - -metadata about each track in the album. not technically an Audius SDK metadata field, but uploaded -as part of the album - -::: - -#### trackFiles - -1. each `/ReleaseList/Release/` except the release with the attribute `IsMainRelease="true"` - -:::info - -array of audio files which the album is comprised of. not technically an Audius SDK metadata field, -but uploaded as part of the album - -::: diff --git a/docs/sidebars.js b/docs/sidebars.js index 35497c82ea8..ec879f462f5 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -84,16 +84,18 @@ module.exports = { { type: 'category', label: 'Specification', - items: ['distributors/specification/overview', 'distributors/specification/ern3', 'distributors/specification/ern4'], + items: [ + 'distributors/specification/overview', + 'distributors/specification/metadata', + 'distributors/specification/ern3', + 'distributors/specification/ern4', + ], collapsed: false, }, { type: 'category', label: 'Self Serve', - items: [ - 'distributors/self-serve/overview', - 'distributors/self-serve/run-a-ddex-server', - ], + items: ['distributors/self-serve/overview', 'distributors/self-serve/run-a-ddex-server'], collapsed: false, }, ], From 8df78a53b5ea2a9b303aeda681f5916295c628ec Mon Sep 17 00:00:00 2001 From: Sam Gutentag <1404219+samgutentag@users.noreply.github.com> Date: Fri, 5 Apr 2024 17:08:03 -0700 Subject: [PATCH 07/12] formatting updates --- docs/.vscode/spellright.dict | 3 + .../distributors/specification/metadata.mdx | 73 +++++++------------ 2 files changed, 30 insertions(+), 46 deletions(-) diff --git a/docs/.vscode/spellright.dict b/docs/.vscode/spellright.dict index 9e98df4c00c..387af6ea894 100644 --- a/docs/.vscode/spellright.dict +++ b/docs/.vscode/spellright.dict @@ -23,9 +23,11 @@ gravatar img io ioredis +isrc js jwt mainnet +metadatas metamask multisig nft @@ -33,6 +35,7 @@ nodejs nonpayable npm oauth +oauthed off-chain on-chain onclick diff --git a/docs/docs/distributors/specification/metadata.mdx b/docs/docs/distributors/specification/metadata.mdx index f91f50a49f5..ab78810c891 100644 --- a/docs/docs/distributors/specification/metadata.mdx +++ b/docs/docs/distributors/specification/metadata.mdx @@ -8,7 +8,7 @@ description: Audius SDK to DDEX Metadata Mapping import useBaseUrl from '@docusaurus/useBaseUrl' -:::info The following is provided based on ERN3.8 +:::info The following is provided based on [ERN3.8](/distributors/specification/ern3) Please note that exact DDEX fields will depend on the specific ERN version. @@ -50,7 +50,7 @@ this DDEX field is a relative path to the file within the delivery :::info -not technically an Audius SDK metadata field, but uploaded as part of the track/album +Not technically an Audius SDK metadata field, but uploaded as part of the track/album ::: @@ -67,9 +67,10 @@ from a DDEX delivery in cascading precedence. :::info -from this element, we parse+preserve many IDs (children elements): `PartyId`, `CatalogNumber`, -`ICPN`, `GRid`, `ISAN`, `ISBN`, `ISMN`, `ISRC`, `ISSN`, `ISTC`, `ISWC`, `MWLI`, `SICI`, and -`ProprietaryId` +The following fields are parsed and preserved from this field: + +`PartyId`, `CatalogNumber`, `ICPN`, `GRid`, `ISAN`, `ISBN`, `ISMN`, `ISRC`, `ISSN`, `ISTC`, `ISWC`, +`MWLI`, `SICI`, and `ProprietaryId` ::: @@ -83,23 +84,6 @@ The DDEX standard includes a `MarketingComments` field that is rarely used, but The following Audius SDK Fields are not used by DDEX and have no mapping. -#### license - -:::info - -we don’t know which DDEX field to use for this, but it seems like something that would be -communicated somewhere - -::: - -#### mood and tags - -:::info - -never passed to Audius SDK because DDEX doesn’t provide these and likely never will - -::: - #### child elements of `/ReleaseList/Release/` The following child elements are parsed and stored in the separate DDEX server, but not stored in @@ -150,10 +134,8 @@ from a DDEX delivery in cascading precedence. :::info -Subtitle is currently ignored/unused, which likely needs to change (perhaps make title be -`“<title> - <subtitle>.”` also note that DDEX communicates additional titles (eg, -`<Title TitleType=”DisplayTitle”>` and `<Title TitleType=”FormalTitle”>`) in the both the -SoundRecording and release. we store these in the separate DDEX server but not in the Audius network +Subtitle is currently ignored/unused in the both the SoundRecording and release and are stored in +the separate DDEX server but not in the Audius network. ::: @@ -166,8 +148,8 @@ the `trackFile` maps to two DDEX Fields :::info -the actual audio file. not technically an Audius SDK metadata field, but uploaded in the same SDK -function. note that this DDEX field is a relative path to the file within the delivery +This is the actual audio file, not technically an Audius SDK metadata field, but uploaded in the +same SDK function. Note that this DDEX field is a relative path to the file within the delivery ::: @@ -185,7 +167,7 @@ from a DDEX delivery in cascading precedence. :::info -we use the `/PartyName/FullName` child element as the artist’s name and the `SequenceNumber` +The `/PartyName/FullName` child element is used as the artist’s name and the `SequenceNumber` attribute to preserve order ::: @@ -198,8 +180,8 @@ attribute to preserve order :::info -only used if both year AND text are non-empty. the child elements that are parsed are: `Year` and -`CLineText` +This is only used if both `year` _AND_ `text` are non-empty. The child elements that are parsed are: +`Year` and `CLineText` ::: @@ -211,8 +193,8 @@ only used if both year AND text are non-empty. the child elements that are parse :::info -only used if both year AND text are non-empty. the child elements that are parsed are: `Year` and -`PLineText` +This is only used if both `year` _AND_ `text` are non-empty. The child elements that are parsed are: +`Year` and `CLineText` ::: @@ -231,7 +213,7 @@ only used if both year AND text are non-empty. the child elements that are parse :::info -the following children elements are parsed and stored in Audius: `PartyName`/`FullName`, +The following children elements are parsed and stored in Audius: `PartyName`/`FullName`, `SequenceNumber`, and `ResourceContributorRole` ::: @@ -242,7 +224,7 @@ the following children elements are parsed and stored in Audius: `PartyName`/`Fu :::info -the following children elements are parsed and stored in Audius: `PartyName`/`FullName`, +The following children elements are parsed and stored in Audius: `PartyName`/`FullName`, `SequenceNumber`, and `IndirectResourceContributorRole` ::: @@ -253,7 +235,7 @@ the following children elements are parsed and stored in Audius: `PartyName`/`Fu :::info -the following children elements are parsed and stored in Audius: `PartyName`/`FullName`, +The following children elements are parsed and stored in Audius: `PartyName`/`FullName`, `RightsShareUnknown`, and `RightsControllerRole` ::: @@ -287,9 +269,8 @@ from a DDEX delivery in cascading precedence. :::info -subtitle is currently ignored/unused, which likely needs to change (perhaps make title be -`“<title> - <subtitle>.”` the same element but with `TitleType=’FormalTitle’`, as well as a -`<ReferenceTitle>` element, are stored in the separate DDEX server but not in the Audius network +Subtitle is currently ignored/unused in the both the SoundRecording and release and are stored in +the separate DDEX server but not in the Audius network. ::: @@ -304,7 +285,7 @@ subtitle is currently ignored/unused, which likely needs to change (perhaps make :::info -metadata about each track in the album. not technically an Audius SDK metadata field, but uploaded +Metadata about each track in the album, not technically an Audius SDK metadata field, but uploaded as part of the album ::: @@ -315,7 +296,7 @@ as part of the album :::info -array of audio files which the album is comprised of. not technically an Audius SDK metadata field, +array of audio files which the album is comprised of, not technically an Audius SDK metadata field, but uploaded as part of the album ::: @@ -333,7 +314,7 @@ from a DDEX delivery in cascading precedence. :::info -we use the `/PartyName/FullName` child element as the artist’s name and the `SequenceNumber` +The `/PartyName/FullName` child element is used as the artist’s name and the `SequenceNumber` attribute to preserve order ::: @@ -345,8 +326,8 @@ attribute to preserve order :::info -only used if both year AND text are non-empty. the child elements that are parsed are: `Year` and -`CLineText` +This is only used if both `year` _AND_ `text` are non-empty. The child elements that are parsed are: +`Year` and `CLineText` ::: @@ -357,8 +338,8 @@ only used if both year AND text are non-empty. the child elements that are parse :::info -only used if both year AND text are non-empty. the child elements that are parsed are: `Year` and -`PLineText` +This is only used if both `year` _AND_ `text` are non-empty. The child elements that are parsed are: +`Year` and `PLineText` ::: From d71d330899eaef5367c123f24504766e4cf3d076 Mon Sep 17 00:00:00 2001 From: Raymond Jacobson <ray@audius.co> Date: Fri, 5 Apr 2024 19:58:18 -0700 Subject: [PATCH 08/12] Minor changes --- .../distributors/introduction/overview.mdx | 13 +++-- .../distributors/specification/metadata.mdx | 49 ++++++++----------- 2 files changed, 29 insertions(+), 33 deletions(-) diff --git a/docs/docs/distributors/introduction/overview.mdx b/docs/docs/distributors/introduction/overview.mdx index 6b9b813a7b3..ffb701cec7c 100644 --- a/docs/docs/distributors/introduction/overview.mdx +++ b/docs/docs/distributors/introduction/overview.mdx @@ -8,15 +8,19 @@ description: Audius Protocol Documentation import useBaseUrl from '@docusaurus/useBaseUrl' -:::tip Looking for how to accept uploads from your distributor? +:::tip Looking for how to accept deliveries from your label or distributor? -Visit [ddex.audius.co](https://ddex.audius.co) and check the +Come back soon and check the [Audius Support Page](https://support.audius.co) for more information. ::: Audius supports bulk content ingestion via the DDEX standard. +Providers, labels & partners with +their own delivery infrastructure should reference the following documentation for guidance on how +to send and administer content on Audius. + If you're looking to build your own ingestion tooling, get started with the [Audius SDK](/developers/sdk/overview). @@ -29,7 +33,7 @@ supply chain more efficiently by: - Developing standard message and file formats (XML or flat-file) - Developing choreographies for specific business transactions - Developing communication protocols (SFTP or based on web services) -- Working with industry bodies to create a more efficient supply chain. +- Working with industry bodies to create a more efficient supply chain ### More Information @@ -46,4 +50,5 @@ All DDEX ingestion code & libraries are open source and available on You may clone and self-operate your own Audius compatible DDEX ingestion server, which provides a web interface to deliver files, manage uploads, and track success. Under the hood, DDEX ingestion -uses the [Audius SDK](/developers/sdk/overview) to process and upload tracks. +uses the [Audius SDK](/developers/sdk/overview) to process and upload tracks and is available in a +[self-service](./self-service) manner. diff --git a/docs/docs/distributors/specification/metadata.mdx b/docs/docs/distributors/specification/metadata.mdx index ab78810c891..71df003cd3d 100644 --- a/docs/docs/distributors/specification/metadata.mdx +++ b/docs/docs/distributors/specification/metadata.mdx @@ -1,6 +1,6 @@ --- id: metadata -title: Metadata Mapping +title: Supported Metadata Mapping pagination_label: Metadata Mapping sidebar_label: Metadata Mapping description: Audius SDK to DDEX Metadata Mapping @@ -16,8 +16,6 @@ Please note that exact DDEX fields will depend on the specific ERN version. --- -## Metadata Mapping - ### Required Fields The following metadata fields are required for content to be listed on Audius and are examined and @@ -36,19 +34,12 @@ the `coverArtFile` maps to two DDEX Fields - `/ResourceList/Image/ImageDetailsByTerritory[TerritoryCode="Worldwide"]/TechnicalImageDetails/File/FilePath` - `/ResourceList/Image/ImageDetailsByTerritory[TerritoryCode="Worldwide"]/TechnicalImageDetails/File/FileName` -:::info - -Not technically an Audius SDK metadata field, but uploaded as part of the track/album. note that -this DDEX field is a relative path to the file within the delivery - -::: - #### userId 1. same as artists (next row below): checks each artist name (in order) against Audius database of OAuthed display names, and uses the first match -:::info +:::note Not technically an Audius SDK metadata field, but uploaded as part of the track/album @@ -65,7 +56,7 @@ from a DDEX delivery in cascading precedence. 1. `/ReleaseList/Release/ReleaseId` -:::info +:::note The following fields are parsed and preserved from this field: @@ -132,7 +123,7 @@ from a DDEX delivery in cascading precedence. 1. `/ResourceList/SoundRecording/ReferenceTitle/TitleText` -:::info +:::note Subtitle is currently ignored/unused in the both the SoundRecording and release and are stored in the separate DDEX server but not in the Audius network. @@ -146,7 +137,7 @@ the `trackFile` maps to two DDEX Fields - `/ResourceList/SoundRecording/SoundDetailsByTerritory[TerritoryCode="Worldwide"]/TechnicalSoundRecordingDetails/File/FilePath` - `/ResourceList/SoundRecording/SoundDetailsByTerritory[TerritoryCode="Worldwide"]/TechnicalSoundRecordingDetails/File/FileName` -:::info +:::note This is the actual audio file, not technically an Audius SDK metadata field, but uploaded in the same SDK function. Note that this DDEX field is a relative path to the file within the delivery @@ -165,7 +156,7 @@ from a DDEX delivery in cascading precedence. 1. `/ResourceList/SoundRecording/SoundRecordingDetailsByTerritory[TerritoryCode="Worldwide"]/DisplayArtist` 2. `/ReleaseList/Release/ReleaseDetailsByTerritory[TerritoryCode="Worldwide"]/DisplayArtist` -:::info +:::note The `/PartyName/FullName` child element is used as the artist’s name and the `SequenceNumber` attribute to preserve order @@ -178,7 +169,7 @@ attribute to preserve order 2. `/ReleaseList/Release/ReleaseDetailsByTerritory[TerritoryCode="Worldwide"]/CLine` 3. `/ReleaseList/Release/CLine` -:::info +:::note This is only used if both `year` _AND_ `text` are non-empty. The child elements that are parsed are: `Year` and `CLineText` @@ -191,7 +182,7 @@ This is only used if both `year` _AND_ `text` are non-empty. The child elements 2. `/ReleaseList/Release/ReleaseDetailsByTerritory[TerritoryCode="Worldwide"]/PLine` 3. `/ReleaseList/Release/PLine` -:::info +:::note This is only used if both `year` _AND_ `text` are non-empty. The child elements that are parsed are: `Year` and `CLineText` @@ -211,7 +202,7 @@ This is only used if both `year` _AND_ `text` are non-empty. The child elements 1. `/ResourceList/SoundRecording/SoundDetailsByTerritory[TerritoryCode="Worldwide"]/ResourceContributor` -:::info +:::note The following children elements are parsed and stored in Audius: `PartyName`/`FullName`, `SequenceNumber`, and `ResourceContributorRole` @@ -222,7 +213,7 @@ The following children elements are parsed and stored in Audius: `PartyName`/`Fu 1. `/ResourceList/SoundRecording/SoundDetailsByTerritory[TerritoryCode="Worldwide"]/IndirectResourceContributor` -:::info +:::note The following children elements are parsed and stored in Audius: `PartyName`/`FullName`, `SequenceNumber`, and `IndirectResourceContributorRole` @@ -233,7 +224,7 @@ The following children elements are parsed and stored in Audius: `PartyName`/`Fu 1. `/ResourceList/SoundRecording/SoundDetailsByTerritory[TerritoryCode="Worldwide"]/RightsController` -:::info +:::note The following children elements are parsed and stored in Audius: `PartyName`/`FullName`, `RightsShareUnknown`, and `RightsControllerRole` @@ -247,7 +238,7 @@ The following children elements are parsed and stored in Audius: `PartyName`/`Fu `/ResourceList/SoundRecording/SoundDetailsByTerritory[TerritoryCode="Worldwide"]/TechnicalSoundRecordingDetails/IsPreview` is true -:::info +:::note Preview length is 30 seconds starting at the `previewStartSeconds` into the track’s audio, even if a longer or shorter duration is given. does not support using an external file for the preview @@ -267,7 +258,7 @@ from a DDEX delivery in cascading precedence. 1. `/ReleaseList/Release/ReleaseDetailsByTerritory[TerritoryCode="Worldwide"]/Title[@TitleType='DisplayTitle']/TitleText` -:::info +:::note Subtitle is currently ignored/unused in the both the SoundRecording and release and are stored in the separate DDEX server but not in the Audius network. @@ -283,7 +274,7 @@ the separate DDEX server but not in the Audius network. 1. each `/ReleaseList/Release/` except the release with the attribute `IsMainRelease="true"` -:::info +:::note Metadata about each track in the album, not technically an Audius SDK metadata field, but uploaded as part of the album @@ -294,7 +285,7 @@ as part of the album 1. each `/ReleaseList/Release/` except the release with the attribute `IsMainRelease="true"` -:::info +:::note array of audio files which the album is comprised of, not technically an Audius SDK metadata field, but uploaded as part of the album @@ -312,7 +303,7 @@ from a DDEX delivery in cascading precedence. 1. `/ReleaseList/Release/ReleaseDetailsByTerritory[TerritoryCode="Worldwide"]/DisplayArtist` -:::info +:::note The `/PartyName/FullName` child element is used as the artist’s name and the `SequenceNumber` attribute to preserve order @@ -321,10 +312,10 @@ attribute to preserve order #### copyrightLine -1`/ReleaseList/Release/ReleaseDetailsByTerritory[TerritoryCode="Worldwide"]/CLine` 2. -`/ReleaseList/Release/CLine` +1. `/ReleaseList/Release/ReleaseDetailsByTerritory[TerritoryCode="Worldwide"]/CLine` +2. `/ReleaseList/Release/CLine` -:::info +:::note This is only used if both `year` _AND_ `text` are non-empty. The child elements that are parsed are: `Year` and `CLineText` @@ -336,7 +327,7 @@ This is only used if both `year` _AND_ `text` are non-empty. The child elements 1. `/ReleaseList/Release/ReleaseDetailsByTerritory[TerritoryCode="Worldwide"]/PLine` 2. `/ReleaseList/Release/PLine` -:::info +:::note This is only used if both `year` _AND_ `text` are non-empty. The child elements that are parsed are: `Year` and `PLineText` From ce11ee4d3765d6786ec8cc12b3583dfe02f5ee56 Mon Sep 17 00:00:00 2001 From: Sam Gutentag <1404219+samgutentag@users.noreply.github.com> Date: Mon, 8 Apr 2024 12:40:20 -0700 Subject: [PATCH 09/12] add `upc` and `iswc` fields, alphabetize --- .../distributors/specification/metadata.mdx | 100 ++++++++++-------- 1 file changed, 58 insertions(+), 42 deletions(-) diff --git a/docs/docs/distributors/specification/metadata.mdx b/docs/docs/distributors/specification/metadata.mdx index 71df003cd3d..238657e54e1 100644 --- a/docs/docs/distributors/specification/metadata.mdx +++ b/docs/docs/distributors/specification/metadata.mdx @@ -21,12 +21,6 @@ Please note that exact DDEX fields will depend on the specific ERN version. The following metadata fields are required for content to be listed on Audius and are examined and pulled from a DDEX delivery in cascading precedence. -#### releaseDate - -1. `/DealList/ReleaseDeal/Deal/ValidityPeriod/StartDate` -2. `/ReleaseList/Release/ReleaseDetailsByTerritory[TerritoryCode="Worldwide"]/ReleaseDate` -3. `/ReleaseList/Release/GlobalOriginalReleaseDate` - #### coverArtFile the `coverArtFile` maps to two DDEX Fields @@ -34,6 +28,12 @@ the `coverArtFile` maps to two DDEX Fields - `/ResourceList/Image/ImageDetailsByTerritory[TerritoryCode="Worldwide"]/TechnicalImageDetails/File/FilePath` - `/ResourceList/Image/ImageDetailsByTerritory[TerritoryCode="Worldwide"]/TechnicalImageDetails/File/FileName` +#### releaseDate + +1. `/DealList/ReleaseDeal/Deal/ValidityPeriod/StartDate` +2. `/ReleaseList/Release/ReleaseDetailsByTerritory[TerritoryCode="Worldwide"]/ReleaseDate` +3. `/ReleaseList/Release/GlobalOriginalReleaseDate` + #### userId 1. same as artists (next row below): checks each artist name (in order) against Audius database of @@ -176,72 +176,76 @@ This is only used if both `year` _AND_ `text` are non-empty. The child elements ::: -#### producerCopyrightLine +#### indirectResourceContributors -1. `/ResourceList/SoundRecording/SoundRecordingDetailsByTerritory[TerritoryCode="Worldwide"]/PLine` -2. `/ReleaseList/Release/ReleaseDetailsByTerritory[TerritoryCode="Worldwide"]/PLine` -3. `/ReleaseList/Release/PLine` +1. `/ResourceList/SoundRecording/SoundDetailsByTerritory[TerritoryCode="Worldwide"]/IndirectResourceContributor` :::note -This is only used if both `year` _AND_ `text` are non-empty. The child elements that are parsed are: -`Year` and `CLineText` +The following children elements are parsed and stored in Audius: `PartyName`/`FullName`, +`SequenceNumber`, and `IndirectResourceContributorRole` ::: +#### isrc + +1. `/ResourceList/SoundRecording/SoundRecordingId/ISRC` + +#### iswc + +1. `/ReleaseList/Release/ReleaseId/ISWC` + #### parentalWarningType 1. `/ResourceList/SoundRecording/SoundRecordingDetailsByTerritory[TerritoryCode="Worldwide"]/ParentalWarningType` 2. `/ReleaseList/Release/ReleaseDetailsByTerritory[TerritoryCode="Worldwide"]/ParentalWarningType` -#### isrc - -1. `/ResourceList/SoundRecording/SoundRecordingId/ISRC` - -#### resourceContributors +#### previewStartSeconds -1. `/ResourceList/SoundRecording/SoundDetailsByTerritory[TerritoryCode="Worldwide"]/ResourceContributor` +1. `/ResourceList/SoundRecording/SoundDetailsByTerritory[TerritoryCode="Worldwide"]/TechnicalSoundRecordingDetails/PreviewDetails/StartPoint` +2. only when + `/ResourceList/SoundRecording/SoundDetailsByTerritory[TerritoryCode="Worldwide"]/TechnicalSoundRecordingDetails/IsPreview` + is true :::note -The following children elements are parsed and stored in Audius: `PartyName`/`FullName`, -`SequenceNumber`, and `ResourceContributorRole` +Preview length is 30 seconds starting at the `previewStartSeconds` into the track’s audio, even if a +longer or shorter duration is given. does not support using an external file for the preview ::: -#### indirectResourceContributors +#### producerCopyrightLine -1. `/ResourceList/SoundRecording/SoundDetailsByTerritory[TerritoryCode="Worldwide"]/IndirectResourceContributor` +1. `/ResourceList/SoundRecording/SoundRecordingDetailsByTerritory[TerritoryCode="Worldwide"]/PLine` +2. `/ReleaseList/Release/ReleaseDetailsByTerritory[TerritoryCode="Worldwide"]/PLine` +3. `/ReleaseList/Release/PLine` :::note -The following children elements are parsed and stored in Audius: `PartyName`/`FullName`, -`SequenceNumber`, and `IndirectResourceContributorRole` +This is only used if both `year` _AND_ `text` are non-empty. The child elements that are parsed are: +`Year` and `CLineText` ::: -#### rightsController +#### resourceContributors -1. `/ResourceList/SoundRecording/SoundDetailsByTerritory[TerritoryCode="Worldwide"]/RightsController` +1. `/ResourceList/SoundRecording/SoundDetailsByTerritory[TerritoryCode="Worldwide"]/ResourceContributor` :::note The following children elements are parsed and stored in Audius: `PartyName`/`FullName`, -`RightsShareUnknown`, and `RightsControllerRole` +`SequenceNumber`, and `ResourceContributorRole` ::: -#### previewStartSeconds +#### rightsController -1. `/ResourceList/SoundRecording/SoundDetailsByTerritory[TerritoryCode="Worldwide"]/TechnicalSoundRecordingDetails/PreviewDetails/StartPoint` -2. only when - `/ResourceList/SoundRecording/SoundDetailsByTerritory[TerritoryCode="Worldwide"]/TechnicalSoundRecordingDetails/IsPreview` - is true +1. `/ResourceList/SoundRecording/SoundDetailsByTerritory[TerritoryCode="Worldwide"]/RightsController` :::note -Preview length is 30 seconds starting at the `previewStartSeconds` into the track’s audio, even if a -longer or shorter duration is given. does not support using an external file for the preview +The following children elements are parsed and stored in Audius: `PartyName`/`FullName`, +`RightsShareUnknown`, and `RightsControllerRole` ::: @@ -270,25 +274,25 @@ the separate DDEX server but not in the Audius network. 1. `/ReleaseList/Release/ReleaseDetailsByTerritory[TerritoryCode="Worldwide"]/Genre/SubGenre` 2. `/ReleaseList/Release/ReleaseDetailsByTerritory[TerritoryCode="Worldwide"]/Genre/GenreText` -#### trackMetadatas +#### trackFiles 1. each `/ReleaseList/Release/` except the release with the attribute `IsMainRelease="true"` :::note -Metadata about each track in the album, not technically an Audius SDK metadata field, but uploaded -as part of the album +array of audio files which the album is comprised of, not technically an Audius SDK metadata field, +but uploaded as part of the album ::: -#### trackFiles +#### trackMetadatas 1. each `/ReleaseList/Release/` except the release with the attribute `IsMainRelease="true"` :::note -array of audio files which the album is comprised of, not technically an Audius SDK metadata field, -but uploaded as part of the album +Metadata about each track in the album, not technically an Audius SDK metadata field, but uploaded +as part of the album ::: @@ -322,6 +326,10 @@ This is only used if both `year` _AND_ `text` are non-empty. The child elements ::: +#### parentalWarningType + +1. `/ReleaseList/Release/ReleaseDetailsByTerritory[TerritoryCode="Worldwide"]/ParentalWarningType` + #### producerCopyrightLine 1. `/ReleaseList/Release/ReleaseDetailsByTerritory[TerritoryCode="Worldwide"]/PLine` @@ -334,6 +342,14 @@ This is only used if both `year` _AND_ `text` are non-empty. The child elements ::: -#### parentalWarningType +#### upc -1. `/ReleaseList/Release/ReleaseDetailsByTerritory[TerritoryCode="Worldwide"]/ParentalWarningType` +1. `/ReleaseList/Release/ReleaseId/ICPN` + +:::note + +ICPN (or "International Code Product Number") has an `IsEAN` attribute which determines if it’s an +EAN (European Article Number) or UPC (Universal Product Code — only used in US and Canada). We use +them interchangeably and just set it as UPC even if it’s an EAN + +::: From 3502c3b63e6dfa181cc8ff7ccae68a271b5160fb Mon Sep 17 00:00:00 2001 From: Sam Gutentag <1404219+samgutentag@users.noreply.github.com> Date: Mon, 8 Apr 2024 12:43:45 -0700 Subject: [PATCH 10/12] ref link fixup --- docs/docs/distributors/introduction/overview.mdx | 10 ++++------ docs/docs/distributors/self-serve/overview.mdx | 6 ++---- 2 files changed, 6 insertions(+), 10 deletions(-) diff --git a/docs/docs/distributors/introduction/overview.mdx b/docs/docs/distributors/introduction/overview.mdx index ffb701cec7c..a64d6f1a9d3 100644 --- a/docs/docs/distributors/introduction/overview.mdx +++ b/docs/docs/distributors/introduction/overview.mdx @@ -10,16 +10,14 @@ import useBaseUrl from '@docusaurus/useBaseUrl' :::tip Looking for how to accept deliveries from your label or distributor? -Come back soon and check the -[Audius Support Page](https://support.audius.co) for more information. +Come back soon and check the [Audius Support Page](https://support.audius.co) for more information. ::: Audius supports bulk content ingestion via the DDEX standard. -Providers, labels & partners with -their own delivery infrastructure should reference the following documentation for guidance on how -to send and administer content on Audius. +Providers, labels & partners with their own delivery infrastructure should reference the following +documentation for guidance on how to send and administer content on Audius. If you're looking to build your own ingestion tooling, get started with the [Audius SDK](/developers/sdk/overview). @@ -51,4 +49,4 @@ All DDEX ingestion code & libraries are open source and available on You may clone and self-operate your own Audius compatible DDEX ingestion server, which provides a web interface to deliver files, manage uploads, and track success. Under the hood, DDEX ingestion uses the [Audius SDK](/developers/sdk/overview) to process and upload tracks and is available in a -[self-service](./self-service) manner. +[self-service](/distributors/self-serve/overview) manner. diff --git a/docs/docs/distributors/self-serve/overview.mdx b/docs/docs/distributors/self-serve/overview.mdx index 552346e02c0..5c2480afb6e 100644 --- a/docs/docs/distributors/self-serve/overview.mdx +++ b/docs/docs/distributors/self-serve/overview.mdx @@ -10,11 +10,9 @@ import useBaseUrl from '@docusaurus/useBaseUrl' --- -Content can be ingested into the Audius network by directly operating your own DDEX ingestion -server. - :::info -More details soon +Content can be ingested into the Audius network by directly operating your own DDEX ingestion +server. More details soon. ::: From e9bdf37ef8cfb63b4c6bc2ef378aa1f9456978c1 Mon Sep 17 00:00:00 2001 From: Sam Gutentag <1404219+samgutentag@users.noreply.github.com> Date: Mon, 8 Apr 2024 13:15:07 -0700 Subject: [PATCH 11/12] copy pass, formatting --- docs/.vscode/spellright.dict | 2 + .../distributors/introduction/overview.mdx | 4 +- docs/docs/distributors/specification/ern3.mdx | 234 +++++++++--------- .../distributors/specification/metadata.mdx | 105 ++++---- .../distributors/specification/overview.mdx | 5 +- 5 files changed, 168 insertions(+), 182 deletions(-) diff --git a/docs/.vscode/spellright.dict b/docs/.vscode/spellright.dict index 387af6ea894..42c44bdce01 100644 --- a/docs/.vscode/spellright.dict +++ b/docs/.vscode/spellright.dict @@ -24,6 +24,7 @@ img io ioredis isrc +iswc js jwt mainnet @@ -61,6 +62,7 @@ typehash undelegate unrepost unstake +upc userbase wei whitepaper \ No newline at end of file diff --git a/docs/docs/distributors/introduction/overview.mdx b/docs/docs/distributors/introduction/overview.mdx index a64d6f1a9d3..d0cc7e10b19 100644 --- a/docs/docs/distributors/introduction/overview.mdx +++ b/docs/docs/distributors/introduction/overview.mdx @@ -33,12 +33,14 @@ supply chain more efficiently by: - Developing communication protocols (SFTP or based on web services) - Working with industry bodies to create a more efficient supply chain -### More Information +:::info More Information - Learn more on the official DDEX Website here: [https://ddex.net/](https://ddex.net/) - Looking for a deeper technical dive? Checkout the DDEX knowledge base here: [https://kb.ddex.net/](https://kb.ddex.net/) +::: + --- ## Open Source diff --git a/docs/docs/distributors/specification/ern3.mdx b/docs/docs/distributors/specification/ern3.mdx index 0f45db762be..7c9fc880772 100644 --- a/docs/docs/distributors/specification/ern3.mdx +++ b/docs/docs/distributors/specification/ern3.mdx @@ -30,13 +30,13 @@ Audius accepts the following DDEX `Deal`s for **track** releases: ### Free To Stream -1. `CommercialModelType`: `FreeOfChargeModel` -2. `UseType`: `Stream` or `OnDemandStream` -3. `PriceType`: not supported -4. `WholesalePricePerUnit`: N/A -5. `ValidityPeriod` - 1. `StartDate`: any -6. `TerritoryCode`: `Worldwide` +1. `CommercialModelType`: `FreeOfChargeModel` +2. `UseType`: `Stream` or `OnDemandStream` +3. `PriceType`: not supported +4. `WholesalePricePerUnit`: N/A +5. `ValidityPeriod` + 1. `StartDate`: any +6. `TerritoryCode`: `Worldwide` ```xml <Deal> @@ -55,13 +55,9 @@ Audius accepts the following DDEX `Deal`s for **track** releases: ### Pay Gated Stream -1. `CommercialModelType`: `PayAsYouGoModel` -2. `UseType`: `Stream` or `OnDemandStream` -3. `PriceType`: not supported -4. `WholesalePricePerUnit`: any nonzero USD amount -5. `ValidityPeriod` - 1. `StartDate`: any -6. `TerritoryCode`: `Worldwide` +`CommercialModelType`: `PayAsYouGoModel` 2. `UseType`: `Stream` or `OnDemandStream` 3. `PriceType`: +not supported 4. `WholesalePricePerUnit`: any nonzero USD amount 5. `ValidityPeriod` 1. `StartDate`: +any 6. `TerritoryCode`: `Worldwide` ```xml <Deal> @@ -72,8 +68,8 @@ Audius accepts the following DDEX `Deal`s for **track** releases: </Usage> <TerritoryCode>Worldwide</TerritoryCode> <PriceInformation> - <WholesalePricePerUnit CurrencyCode="USD">1.0</WholesalePricePerUnit> - ... + <WholesalePricePerUnit CurrencyCode="USD">1.0</WholesalePricePerUnit> + ... </PriceInformation> <ValidityPeriod> <StartDate>2023-09-02</StartDate> @@ -84,13 +80,13 @@ Audius accepts the following DDEX `Deal`s for **track** releases: ### Follow Gated Stream -1. `CommercialModelType`: `UserDefined` (`FollowGated`) -2. `UseType`: `Stream` or `OnDemandStream` -3. `PriceType`: not supported -4. `WholesalePricePerUnit`: N/A -5. `ValidityPeriod` - 1. `StartDate`: any -6. `TerritoryCode`: `Worldwide` +1. `CommercialModelType`: `UserDefined` (`FollowGated`) +2. `UseType`: `Stream` or `OnDemandStream` +3. `PriceType`: not supported +4. `WholesalePricePerUnit`: N/A +5. `ValidityPeriod` + 1. `StartDate`: any +6. `TerritoryCode`: `Worldwide` ```xml <Deal> @@ -109,40 +105,40 @@ Audius accepts the following DDEX `Deal`s for **track** releases: ### NFT Gated Stream -1. `CommercialModelType`: `UserDefined` (`NFTGated`) -2. `UseType`: `Stream` or `OnDemandStream` -3. `PriceType`: not supported -4. `WholesalePricePerUnit`: N/A -5. `ValidityPeriod` - 1. `StartDate`: any -6. `TerritoryCode`: `Worldwide` -7. `Conditions` (custom XML specific to Audius) - - 1. For Ethereum NFTs: - - ```xml - <Conditions> - <Chain>eth</Chain> - <Address></Address> // The Ethereum address of the NFT contract - <Standard></Standard> // The standard followed by the NFT - either "ERC-721" or "ERC-1155" - <Name></Name> // The name of the NFT - <Slug></Slug> // The slug of the NFT collection. E.g. if your collection is located at https://opensea.io/collection/example-nft, the slug is "example-nft". - <ImageUrl></ImageUrl> // Optional: URL to the image representing the NFT - <ExternalLink></ExternalLink> // Optional: URL to an external resource providing more details about the NFT - </Conditions> - ``` - - ii. For Solana NFTs: - - ```xml - <Conditions> - <Chain>sol</Chain> - <Address></Address> // The address of the NFT on the Solana blockchain - <Name></Name> // The name of the NFT - <ImageUrl></ImageUrl> // Optional: URL to the image representing the NFT - <ExternalLink></ExternalLink> // Optional: URL to an external resource providing more details about the NFT - </Conditions> - ``` +1. `CommercialModelType`: `UserDefined` (`NFTGated`) +2. `UseType`: `Stream` or `OnDemandStream` +3. `PriceType`: not supported +4. `WholesalePricePerUnit`: N/A +5. `ValidityPeriod` + 1. `StartDate`: any +6. `TerritoryCode`: `Worldwide` +7. `Conditions` (custom XML specific to Audius) + + 1. For Ethereum NFTs: + + ```xml + <Conditions> + <Chain>eth</Chain> + <Address></Address> // The Ethereum address of the NFT contract + <Standard></Standard> // The standard followed by the NFT - either "ERC-721" or "ERC-1155" + <Name></Name> // The name of the NFT + <Slug></Slug> // The slug of the NFT collection. E.g. if your collection is located at https://opensea.io/collection/example-nft, the slug is "example-nft". + <ImageUrl></ImageUrl> // Optional: URL to the image representing the NFT + <ExternalLink></ExternalLink> // Optional: URL to an external resource providing more details about the NFT + </Conditions> + ``` + + ii. For Solana NFTs: + + ```xml + <Conditions> + <Chain>sol</Chain> + <Address></Address> // The address of the NFT on the Solana blockchain + <Name></Name> // The name of the NFT + <ImageUrl></ImageUrl> // Optional: URL to the image representing the NFT + <ExternalLink></ExternalLink> // Optional: URL to an external resource providing more details about the NFT + </Conditions> + ``` ```xml <Deal> @@ -170,13 +166,13 @@ Audius accepts the following DDEX `Deal`s for **track** releases: ### $AUDIO Tip Gated Stream -1. `CommercialModelType`: `UserDefined` (`TipGated`) -2. `UseType`: `Stream` or `OnDemandStream` -3. `PriceType`: not supported -4. `WholesalePricePerUnit`: N/A -5. `ValidityPeriod` - 1. `StartDate`: any -6. `TerritoryCode`: `Worldwide` +1. `CommercialModelType`: `UserDefined` (`TipGated`) +2. `UseType`: `Stream` or `OnDemandStream` +3. `PriceType`: not supported +4. `WholesalePricePerUnit`: N/A +5. `ValidityPeriod` + 1. `StartDate`: any +6. `TerritoryCode`: `Worldwide` ```xml <Deal> @@ -201,13 +197,13 @@ If you can download it, you can stream it. ::: -1. `CommercialModelType`: `FreeOfChargeModel` -2. `UseType`: `Stream` or `OnDemandStream`, `PermanentDownload` -3. `PriceType`: not supported -4. `WholesalePricePerUnit`: N/A -5. `ValidityPeriod` - 1. `StartDate`: any -6. `TerritoryCode`: `Worldwide` +1. `CommercialModelType`: `FreeOfChargeModel` +2. `UseType`: `Stream` or `OnDemandStream`, `PermanentDownload` +3. `PriceType`: not supported +4. `WholesalePricePerUnit`: N/A +5. `ValidityPeriod` + 1. `StartDate`: any +6. `TerritoryCode`: `Worldwide` ```xml <Deal> @@ -233,13 +229,13 @@ If you can download it, you can stream it. ::: -1. `CommercialModelType`: `PayAsYouGoModel` -2. `UseType`: `Stream` or `OnDemandStream`, `PermanentDownload` -3. `PriceType`: not supported -4. `WholesalePricePerUnit`: any USD amount -5. `ValidityPeriod` - 1. `StartDate`: any -6. `TerritoryCode`: `Worldwide` +1. `CommercialModelType`: `PayAsYouGoModel` +2. `UseType`: `Stream` or `OnDemandStream`, `PermanentDownload` +3. `PriceType`: not supported +4. `WholesalePricePerUnit`: any USD amount +5. `ValidityPeriod` + 1. `StartDate`: any +6. `TerritoryCode`: `Worldwide` ```xml <Deal> @@ -251,8 +247,8 @@ If you can download it, you can stream it. </Usage> <TerritoryCode>Worldwide</TerritoryCode> <PriceInformation> - <WholesalePricePerUnit CurrencyCode="USD">1.0</WholesalePricePerUnit> - ... + <WholesalePricePerUnit CurrencyCode="USD">1.0</WholesalePricePerUnit> + ... </PriceInformation> <ValidityPeriod> <StartDate>2023-09-02</StartDate> @@ -269,13 +265,13 @@ If you can download it, you can stream it. ::: -1. `CommercialModelType`: `UserDefined` (`FollowGated`) -2. `UseType`: `Stream` or `OnDemandStream`, `PermanentDownload` -3. `PriceType`: not supported -4. `WholesalePricePerUnit`: N/A -5. `ValidityPeriod` - 1. `StartDate`: any -6. `TerritoryCode`: `Worldwide` +1. `CommercialModelType`: `UserDefined` (`FollowGated`) +2. `UseType`: `Stream` or `OnDemandStream`, `PermanentDownload` +3. `PriceType`: not supported +4. `WholesalePricePerUnit`: N/A +5. `ValidityPeriod` + 1. `StartDate`: any +6. `TerritoryCode`: `Worldwide` ```xml <Deal> @@ -301,13 +297,13 @@ Audius accepts the following DDEX `Deal`s for **album** releases ### Free To Stream -1. `CommercialModelType`: `FreeOfChargeModel` -2. `UseType`: `Stream` or `OnDemandStream` -3. `PriceType`: not supported -4. `WholesalePricePerUnit`: N/A -5. `ValidityPeriod` - 1. `StartDate`: any -6. `TerritoryCode`: `Worldwide` +1. `CommercialModelType`: `FreeOfChargeModel` +2. `UseType`: `Stream` or `OnDemandStream` +3. `PriceType`: not supported +4. `WholesalePricePerUnit`: N/A +5. `ValidityPeriod` + 1. `StartDate`: any +6. `TerritoryCode`: `Worldwide` ```xml <Deal> @@ -326,13 +322,13 @@ Audius accepts the following DDEX `Deal`s for **album** releases ### Pay Gated Stream -1. `CommercialModelType`: `PayAsYouGoModel` -2. `UseType`: `Stream` or `OnDemandStream` -3. `PriceType`: not supported -4. `WholesalePricePerUnit`: any nonzero USD amount -5. `ValidityPeriod` - 1. `StartDate`: any -6. `TerritoryCode`: `Worldwide` +1. `CommercialModelType`: `PayAsYouGoModel` +2. `UseType`: `Stream` or `OnDemandStream` +3. `PriceType`: not supported +4. `WholesalePricePerUnit`: any nonzero USD amount +5. `ValidityPeriod` + 1. `StartDate`: any +6. `TerritoryCode`: `Worldwide` ```xml <Deal> @@ -343,8 +339,8 @@ Audius accepts the following DDEX `Deal`s for **album** releases </Usage> <TerritoryCode>Worldwide</TerritoryCode> <PriceInformation> - <WholesalePricePerUnit CurrencyCode="USD">1.0</WholesalePricePerUnit> - ... + <WholesalePricePerUnit CurrencyCode="USD">1.0</WholesalePricePerUnit> + ... </PriceInformation> <ValidityPeriod> <StartDate>2023-09-02</StartDate> @@ -361,13 +357,13 @@ If you can download it, you can stream it. ::: -1. `CommercialModelType`: `FreeOfChargeModel` -2. `UseType`: `Stream` or `OnDemandStream`, `PermanentDownload` -3. `PriceType`: not supported -4. `WholesalePricePerUnit`: N/A -5. `ValidityPeriod` - 1. `StartDate`: any -6. `TerritoryCode`: `Worldwide` +1. `CommercialModelType`: `FreeOfChargeModel` +2. `UseType`: `Stream` or `OnDemandStream`, `PermanentDownload` +3. `PriceType`: not supported +4. `WholesalePricePerUnit`: N/A +5. `ValidityPeriod` + 1. `StartDate`: any +6. `TerritoryCode`: `Worldwide` ```xml <Deal> @@ -393,13 +389,13 @@ If you can download it, you can stream it. ::: -1. `CommercialModelType`: `PayAsYouGoModel` -2. `UseType`: `Stream` or `OnDemandStream`, `PermanentDownload` -3. `PriceType`: not supported -4. `WholesalePricePerUnit`: any USD amount -5. `ValidityPeriod` - 1. `StartDate`: any -6. `TerritoryCode`: `Worldwide` +1. `CommercialModelType`: `PayAsYouGoModel` +2. `UseType`: `Stream` or `OnDemandStream`, `PermanentDownload` +3. `PriceType`: not supported +4. `WholesalePricePerUnit`: any USD amount +5. `ValidityPeriod` + 1. `StartDate`: any +6. `TerritoryCode`: `Worldwide` ```xml <Deal> @@ -411,8 +407,8 @@ If you can download it, you can stream it. </Usage> <TerritoryCode>Worldwide</TerritoryCode> <PriceInformation> - <WholesalePricePerUnit CurrencyCode="USD">1.0</WholesalePricePerUnit> - ... + <WholesalePricePerUnit CurrencyCode="USD">1.0</WholesalePricePerUnit> + ... </PriceInformation> <ValidityPeriod> <StartDate>2023-09-02</StartDate> diff --git a/docs/docs/distributors/specification/metadata.mdx b/docs/docs/distributors/specification/metadata.mdx index 238657e54e1..df88fd949ef 100644 --- a/docs/docs/distributors/specification/metadata.mdx +++ b/docs/docs/distributors/specification/metadata.mdx @@ -16,6 +16,8 @@ Please note that exact DDEX fields will depend on the specific ERN version. --- +## General Metadata Mapping + ### Required Fields The following metadata fields are required for content to be listed on Audius and are examined and @@ -23,7 +25,11 @@ pulled from a DDEX delivery in cascading precedence. #### coverArtFile -the `coverArtFile` maps to two DDEX Fields +:::note + +The `coverArtFile` maps to two DDEX Fields + +::: - `/ResourceList/Image/ImageDetailsByTerritory[TerritoryCode="Worldwide"]/TechnicalImageDetails/File/FilePath` - `/ResourceList/Image/ImageDetailsByTerritory[TerritoryCode="Worldwide"]/TechnicalImageDetails/File/FileName` @@ -36,15 +42,15 @@ the `coverArtFile` maps to two DDEX Fields #### userId -1. same as artists (next row below): checks each artist name (in order) against Audius database of - OAuthed display names, and uses the first match - :::note Not technically an Audius SDK metadata field, but uploaded as part of the track/album ::: +1. checks each artist name (in order) against Audius database of OAuthed display names, and uses the + first match + --- ### Optional Fields @@ -77,26 +83,26 @@ The following Audius SDK Fields are not used by DDEX and have no mapping. #### child elements of `/ReleaseList/Release/` -The following child elements are parsed and stored in the separate DDEX server, but not stored in -Audius and not used anywhere: +The following child elements are parsed and stored in the separate DDEX server. Audius does not +store these child fields and they are not used. - `ReferenceTitle/TitleText` - `ReferenceTitle/SubTitle` #### child elements of `/ReleaseList/Release/ReleaseDetailsByTerritory[TerritoryCode="Worldwide"]/` -The following child elements are parsed and stored in the separate DDEX server, but not stored in -Audius and not used anywhere: +The following child elements are parsed and stored in the separate DDEX server. Audius does not +store these child fields and they are not used. - `Title[@TitleType='DisplayTitle']/TitleText` (used in albums/EPs but not single tracks) - `Title[@TitleType='DisplayTitle']/SubTitle` - `Title[@TitleType='FormalTitle']/TitleText` -- `Title[@TitleType='FormalTitle']/SubTitle ` +- `Title[@TitleType='FormalTitle']/SubTitle` #### child elements of `/ReleaseList/Release/ReleaseDetailsByTerritory[TerritoryCode="Worldwide"]/ResourceGroup/` -The following child elements are parsed and stored in the separate DDEX server, but not stored in -Audius and not used anywhere: +The following child elements are parsed and stored in the separate DDEX server. Audius does not +store these child fields and they are not used. - `SequenceNumber` - `ResourceGroupContentItem/ResourceType` @@ -132,54 +138,44 @@ the separate DDEX server but not in the Audius network. #### trackFile -the `trackFile` maps to two DDEX Fields - -- `/ResourceList/SoundRecording/SoundDetailsByTerritory[TerritoryCode="Worldwide"]/TechnicalSoundRecordingDetails/File/FilePath` -- `/ResourceList/SoundRecording/SoundDetailsByTerritory[TerritoryCode="Worldwide"]/TechnicalSoundRecordingDetails/File/FileName` +This is the actual audio file, not technically an Audius SDK metadata field, but uploaded in the +same SDK function. Note that this DDEX field is a relative path to the file within the delivery :::note -This is the actual audio file, not technically an Audius SDK metadata field, but uploaded in the -same SDK function. Note that this DDEX field is a relative path to the file within the delivery +The `trackFile` maps to two DDEX Fields ::: +- `/ResourceList/SoundRecording/SoundDetailsByTerritory[TerritoryCode="Worldwide"]/TechnicalSoundRecordingDetails/File/FilePath` +- `/ResourceList/SoundRecording/SoundDetailsByTerritory[TerritoryCode="Worldwide"]/TechnicalSoundRecordingDetails/File/FileName` + --- -### Optional +### Optional Fields The following fields are optional for content to be listed on Audius and are examined and pulled from a DDEX delivery in cascading precedence. #### artists -1. `/ResourceList/SoundRecording/SoundRecordingDetailsByTerritory[TerritoryCode="Worldwide"]/DisplayArtist` -2. `/ReleaseList/Release/ReleaseDetailsByTerritory[TerritoryCode="Worldwide"]/DisplayArtist` - -:::note - The `/PartyName/FullName` child element is used as the artist’s name and the `SequenceNumber` attribute to preserve order -::: +1. `/ResourceList/SoundRecording/SoundRecordingDetailsByTerritory[TerritoryCode="Worldwide"]/DisplayArtist` +2. `/ReleaseList/Release/ReleaseDetailsByTerritory[TerritoryCode="Worldwide"]/DisplayArtist` #### copyrightLine -1. `/ResourceList/SoundRecording/SoundRecordingDetailsByTerritory[TerritoryCode="Worldwide"]/CLine` -2. `/ReleaseList/Release/ReleaseDetailsByTerritory[TerritoryCode="Worldwide"]/CLine` -3. `/ReleaseList/Release/CLine` - -:::note - This is only used if both `year` _AND_ `text` are non-empty. The child elements that are parsed are: `Year` and `CLineText` -::: +1. `/ResourceList/SoundRecording/SoundRecordingDetailsByTerritory[TerritoryCode="Worldwide"]/CLine` +2. `/ReleaseList/Release/ReleaseDetailsByTerritory[TerritoryCode="Worldwide"]/CLine` +3. `/ReleaseList/Release/CLine` #### indirectResourceContributors -1. `/ResourceList/SoundRecording/SoundDetailsByTerritory[TerritoryCode="Worldwide"]/IndirectResourceContributor` - :::note The following children elements are parsed and stored in Audius: `PartyName`/`FullName`, @@ -187,6 +183,8 @@ The following children elements are parsed and stored in Audius: `PartyName`/`Fu ::: +1. `/ResourceList/SoundRecording/SoundDetailsByTerritory[TerritoryCode="Worldwide"]/IndirectResourceContributor` + #### isrc 1. `/ResourceList/SoundRecording/SoundRecordingId/ISRC` @@ -202,18 +200,14 @@ The following children elements are parsed and stored in Audius: `PartyName`/`Fu #### previewStartSeconds +Preview length is 30 seconds starting at the `previewStartSeconds` into the track’s audio, even if a +longer or shorter duration is given. does not support using an external file for the preview + 1. `/ResourceList/SoundRecording/SoundDetailsByTerritory[TerritoryCode="Worldwide"]/TechnicalSoundRecordingDetails/PreviewDetails/StartPoint` 2. only when `/ResourceList/SoundRecording/SoundDetailsByTerritory[TerritoryCode="Worldwide"]/TechnicalSoundRecordingDetails/IsPreview` is true -:::note - -Preview length is 30 seconds starting at the `previewStartSeconds` into the track’s audio, even if a -longer or shorter duration is given. does not support using an external file for the preview - -::: - #### producerCopyrightLine 1. `/ResourceList/SoundRecording/SoundRecordingDetailsByTerritory[TerritoryCode="Worldwide"]/PLine` @@ -253,7 +247,7 @@ The following children elements are parsed and stored in Audius: `PartyName`/`Fu ## Album Metadata Mapping -### Required +### Required Fields The following fields are required for content to be listed on Audius and are examined and pulled from a DDEX delivery in cascading precedence. @@ -276,43 +270,31 @@ the separate DDEX server but not in the Audius network. #### trackFiles -1. each `/ReleaseList/Release/` except the release with the attribute `IsMainRelease="true"` - -:::note - -array of audio files which the album is comprised of, not technically an Audius SDK metadata field, -but uploaded as part of the album - -::: - -#### trackMetadatas +This is an array of audio files which the album is comprised of, not technically an Audius SDK +metadata field, but uploaded as part of the album. 1. each `/ReleaseList/Release/` except the release with the attribute `IsMainRelease="true"` -:::note +#### trackMetadatas Metadata about each track in the album, not technically an Audius SDK metadata field, but uploaded as part of the album -::: +1. each `/ReleaseList/Release/` except the release with the attribute `IsMainRelease="true"` --- -### Optional +### Optional Fields The following fields are optional for content to be listed on Audius and are examined and pulled from a DDEX delivery in cascading precedence. #### artists -1. `/ReleaseList/Release/ReleaseDetailsByTerritory[TerritoryCode="Worldwide"]/DisplayArtist` - -:::note - The `/PartyName/FullName` child element is used as the artist’s name and the `SequenceNumber` attribute to preserve order -::: +1. `/ReleaseList/Release/ReleaseDetailsByTerritory[TerritoryCode="Worldwide"]/DisplayArtist` #### copyrightLine @@ -349,7 +331,8 @@ This is only used if both `year` _AND_ `text` are non-empty. The child elements :::note ICPN (or "International Code Product Number") has an `IsEAN` attribute which determines if it’s an -EAN (European Article Number) or UPC (Universal Product Code — only used in US and Canada). We use -them interchangeably and just set it as UPC even if it’s an EAN +EAN (or "European Article Number") or UPC ("Universal Product Code" — only used in US and Canada). + +Audius uses these interchangeably and just set it as UPC even if it’s an EAN. ::: diff --git a/docs/docs/distributors/specification/overview.mdx b/docs/docs/distributors/specification/overview.mdx index eedb2e08e5e..351992804c5 100644 --- a/docs/docs/distributors/specification/overview.mdx +++ b/docs/docs/distributors/specification/overview.mdx @@ -13,7 +13,10 @@ import useBaseUrl from '@docusaurus/useBaseUrl' :::info Delivery processing [TikiLabs](https://tikilabs.com) is a facilitator of distributing DDEX directly to the Audius -Protocol For inquiries or support, reach out at support@audius.co. +Protocol. + +For inquiries or support, reach out at +[support@audius.co](mailto:support@audius.co?subject=DDEX%20Support). ::: From 0c401011eba093e6785510b687b8746b0b4bf0a0 Mon Sep 17 00:00:00 2001 From: Sam Gutentag <1404219+samgutentag@users.noreply.github.com> Date: Mon, 8 Apr 2024 15:44:48 -0700 Subject: [PATCH 12/12] rename ern to dealtypes --- .../{ern3.mdx => deal-types.mdx} | 24 +++++++++++++++---- docs/docs/distributors/specification/ern4.mdx | 17 ------------- .../distributors/specification/metadata.mdx | 2 +- .../distributors/specification/overview.mdx | 3 ++- docs/sidebars.js | 3 +-- 5 files changed, 23 insertions(+), 26 deletions(-) rename docs/docs/distributors/specification/{ern3.mdx => deal-types.mdx} (96%) delete mode 100644 docs/docs/distributors/specification/ern4.mdx diff --git a/docs/docs/distributors/specification/ern3.mdx b/docs/docs/distributors/specification/deal-types.mdx similarity index 96% rename from docs/docs/distributors/specification/ern3.mdx rename to docs/docs/distributors/specification/deal-types.mdx index 7c9fc880772..789abd299ee 100644 --- a/docs/docs/distributors/specification/ern3.mdx +++ b/docs/docs/distributors/specification/deal-types.mdx @@ -1,9 +1,9 @@ --- -id: ern3 -title: ERN3 -pagination_label: ERN3 -sidebar_label: ERN3 -description: Support for ERN3 +id: deal-types +title: Deal Types +pagination_label: Deal Types +sidebar_label: Deal Types +description: Support for Deal Types --- import useBaseUrl from '@docusaurus/useBaseUrl' @@ -416,3 +416,17 @@ If you can download it, you can stream it. </DealTerms> </Deal> ``` + +--- + +## ERN4 Support + +:::info Coming Soon + +Support for ERN4 is coming coming soon. + +Checkout the +[DDEX ERN4 Knowledge Base](<https://kb.ddex.net/implementing-each-standard/electronic-release-notification-message-suite-(ern)/ern-4-explained/>) +for information in the meantime. + +::: diff --git a/docs/docs/distributors/specification/ern4.mdx b/docs/docs/distributors/specification/ern4.mdx deleted file mode 100644 index b76df1e412c..00000000000 --- a/docs/docs/distributors/specification/ern4.mdx +++ /dev/null @@ -1,17 +0,0 @@ ---- -id: ern4 -title: ERN4 🚧 -pagination_label: ERN4 🚧 -sidebar_label: ERN4 🚧 -description: Support for ERN4 ---- - -:::info Coming Soon - -Support for ERN4 is coming coming soon. - -Checkout the -[DDEX ERN4 Knowledge Base](<https://kb.ddex.net/implementing-each-standard/electronic-release-notification-message-suite-(ern)/ern-4-explained/>) -for information in the meantime. - -::: diff --git a/docs/docs/distributors/specification/metadata.mdx b/docs/docs/distributors/specification/metadata.mdx index df88fd949ef..8aad26d7b17 100644 --- a/docs/docs/distributors/specification/metadata.mdx +++ b/docs/docs/distributors/specification/metadata.mdx @@ -8,7 +8,7 @@ description: Audius SDK to DDEX Metadata Mapping import useBaseUrl from '@docusaurus/useBaseUrl' -:::info The following is provided based on [ERN3.8](/distributors/specification/ern3) +:::info The following is provided based on [ERN3.8](/distributors/specification/deal-types) Please note that exact DDEX fields will depend on the specific ERN version. diff --git a/docs/docs/distributors/specification/overview.mdx b/docs/docs/distributors/specification/overview.mdx index 351992804c5..7c005871c81 100644 --- a/docs/docs/distributors/specification/overview.mdx +++ b/docs/docs/distributors/specification/overview.mdx @@ -21,7 +21,8 @@ For inquiries or support, reach out at ::: - ERN3 is the preferred DDEX specification for bulk ingestion into Audius. See the - [ERN3 details](/distributors/specification/ern3) for more details around submission choreography. + [ERN3 details](/distributors/specification/deal-types) for more details around submission + choreography. - Audius only accepts price information using absolute prices (e.g. via `WholesalePricePerUnit`). Price codes will be ignored (e.g. `PriceType`). - Audius also does not support `ValidityPeriod` `EndDate`s. This includes using `EndDate` to specify diff --git a/docs/sidebars.js b/docs/sidebars.js index ec879f462f5..ae200ba613a 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -87,8 +87,7 @@ module.exports = { items: [ 'distributors/specification/overview', 'distributors/specification/metadata', - 'distributors/specification/ern3', - 'distributors/specification/ern4', + 'distributors/specification/deal-types', ], collapsed: false, },