The bulk upload tool allows you to import multiple releases into the platform at once using a CSV template. This article explains how to format your metadata, attach assets, and handle common errors.

You can download the latest CSV template at the bottom of this article. In order to check for eligibility, you will need to submit an example bulk csv to support@toolost.com.

General

• Catalog Metadata: Below we describe the format for the CSV bulk upload template. Before you use the tool, it is recommended to use this guide and read it thoroughly.

• Catalogue Assets: Assets won't be uploaded directly to the platform. Instead, the metadata file must include a URL from where the systems can obtain the asset in a single call. Our tool will automatically fetch the assets in real-time, from the given URLs in the CSV.

CSV bulk upload has some limitations:

• This specific template only supports release inserts (excluding Ringtones and video clips).

• Fields that are not supported: Release and track description and notes; Track lyrics, Track start time.

  • These fields cannot be inserted as a part of the bulk upload. You can update these fields from the regular interface once the upload process is complete.

Release and Track Field Definition

From line 8 and on in the CSV bulk upload template, you need to fill in your catalogue metadata info. Each line is for one track and contains the release (album) data as well. This way, if you upload for example a release with 10 tracks, the first part (Release fields) for the line will be filled with the same data for all the tracks (in all 10 lines), and the second part (Track fields) will be different for each of the tracks.

In this example, once you have uploaded the file, if there are no errors in the process, the system will upload 1 album with 10 tracks included.

Fixing Errors

If a release contains errors, it will not be uploaded, but free-of-errors releases will be uploaded in any case. Once the upload is complete, you will be provided with a CSV of failed releases, and details about the errors will appear when clicking on “Details”. This will allow you to fix the failed releases and upload another version of them.

You can do the following regarding tracks relations:

• Attach an existing track to a new release: You can use this tool to attach a track that was already uploaded in the past, to a completely new release. In order to do that, you need to fill in the correct ISRC fields in the “Track Fields” section, and leave all the other fields empty. The “Release Fields” section should be filled as usual.
• Attach a new track to multiple releases: You can upload a new track to be included in multiple new releases within the same CSV file. In order to do that, you need to fill the same track metadata fields in the “Track Fields” section in more than one line and make sure you fill in different “Release Fields” in each of the multiple lines to attach this track to each of these releases.
  • If this track already exists in the catalogue, follow the instructions from #1.

File Format

File must be [CSV] comma-separated fields, optionally enclosed by double quotes, as per RFC4180. File character encoding must be UTF-8 to ensure proper treatment for non-English languages.

Optional fields can be left empty, but their columns must be present in the document to maintain the structure the tool is designed for.

Release Type

Release format will be automatically assigned, following these rules:

Uploading Releases

You will be able to upload your files from the Release Manager. By default, this feature isn’t available in your account and must be activated by your account representative, or by contacting support@toolost.com and including a sample bulk CSV file.

CSV Instructions

Metadata Fields

The first section of the file is a metadata section (lines 1-5). All fields are mandatory and allow our tool to process the file correctly.

Release Fields

Track Fields

Tracks for the release will be numbered from 1 onwards in the order they appear in the CSV bulk upload file. On the 2nd and later track lines for the same release, all release fields must be present and consistent with the 1st release line.

Participants

All artists and other participants' roles and names must be listed in the 'participants' single column. Each participant must be prefixed with his role and a colon. Role and name pairs must be joined with semicolons.

For example:

• Primary artists: Natos, Waor.

• Featuring: Ambkor.

• Remixer: Natos.

• Producer: Waor.

• Composer: Waor.

Participants column should show:

• primary:Natos;primary:Waor;featuring:Ambkor;remixer:Natos;producer:Waor;composer:Waor

Rules for Participants

• Every release and every track must have at least a primary artist.

• In a release or track a single artist can have a single role between primary, performer, featuring, and with.

• For any release that is assigned a genre other than non-spoken, there must be at least one composer on each track.

• The primary artist must be the first listed participant in the sequence.

Currently Accepted Participant Role Names (in Lowercase)

• primary

• performer

• producer

• remixer

• composer

• author

• editor

• featuring

• with

• conductor

• arranger

• orchestra

• actor

Duplicated Track in the Same CSV File

If you need to create a new track, with a specified ISRC, that will be shared in two or more releases, you can accomplish this by repeating the track in all of those releases, but take special care that the information of each track must be the same for all duplications.

If some track information differs from the others then all tracks will be marked as failed.

This shared track must have an assigned ISRC, they can't be an AUTO ISRC.

Repeated Track in the User's Catalogue

You can assign an existing track in the user's catalogue to a newly created release.

To accomplish this, in the CSV file we must leave empty all the track information except ISRC, which is the data we use to find the existing track in the user's catalogue.

How to Attach Assets Files

In the asset links fields (cover_url on release level, and audio_url on track level), you need to link to an available file so we can fetch it and upload it with your content.

Assets are mandatory and if any of the links fail, the release cannot be uploaded. Therefore, you need the ensure that the URLs point to the right assets.
If the URLs (e.g. WeTransfer) or the authentication credentials (e.g. S3 signed URLs) last only for a limited time, ensure that the time is long enough to allow the system to ingest the assets.

Please review our Audio files requirements guide.

Please review our Cover art requirements guide.

Asset Ingestion Supported Methods

Assets won't be uploaded directly to the platform. Instead, the metadata file must include a URL from where the systems can obtain the asset in a single call. It means that the URL has to be unique for each asset. For example, the cover link can be repeated for each track in the album, but the audio has to be one for each track (as the audio is different). The URL has to be a direct downloading link.

Authentication credentials of any kind must be included in the URL. The ingestion process won't follow any kind of separate login procedure.

The metadata does not have to be hosted permanently in the external URL, it only needs to be accessible while we retrieve it to process the album on our platform. Indeed from there on the audio and cover are stored in our system. 

We currently support the following options:

• Public URLs:

  • HTTP URLs

  • HTTPS URLs

  • FTP URLs

  • SFTP URLs

  • Amazon S3 URLs (with a signed URL if the asset is read-protected) (this is the preferred method)

  • Cloud storage services that provide public direct downloadable links (such as Dropbox; WeTransfer; Google Drive)

• Authenticated URLs:
  We support some methods of authenticated URLs, only with user and password. In order to include authenticated link, follow this formats:

  • Http URLs:http://{user}:{pass}@{host}/{file}

  • Https URLs:https://{user}:{pass}@{host}/{file}

  • FTP URLs: ftp://{user}:{pass}@{host}/{file}

  • SFTP URLs*:sftp://{user}:{pass}@{host}/{file}

  • Amazon S3 URLs**:https://{bucket}.s3.amazonaws.com/{file}?AWSAccessKeyId={accesskey}&Signature={signature}&Expires={timestamp}

* We only support public keys for SFTP URLs. In order to provide us with a public key, please contact our support center and coordinate your upload with our team.
** Amazon S3 URLs - with a signed URL if the asset is read-protected.

Creative Commons Licenses

We currently support only cc version 3.0. Use the 'license_info' to show creative commons clauses with the official acronyms, hyphen separated.