Development/Seeding/Release Editor: Difference between revisions
No edit summary |
(there is no medium position field. see MBS-7444) |
||
(19 intermediate revisions by 7 users not shown) | |||
Line 1: | Line 1: | ||
This page documents a list of parameters you can POST to the release editor to |
This page documents a list of parameters you can POST to the release editor to “seed” it. All values are optional unless otherwise stated. |
||
To create a new release: http://musicbrainz.org/release/add |
To create a new release: http://musicbrainz.org/release/add |
||
The MusicBrainz server includes an example which demonstrates seeding: [http://musicbrainz.org/static/tests/seed-love-bug.html seed-love-bug.html]. |
|||
== Release data == |
== Release data == |
||
; name |
; <code>name</code> |
||
: The name of the release. Non-empty string. Required |
: The name of the release. Non-empty string. '''Required''' |
||
=== Release group data === |
|||
; comment |
|||
<blockquote> |
|||
We can either re-use an existing release group with |
|||
; <code>release_group</code> |
|||
: The MBID of an existing release group |
|||
Or we can create a new release group which will have the name of the release by listing its type(s) |
|||
; <code>type</code> |
|||
: The type(s) of the release group that will be created. The possible values are the names of the release group types, in English (see [[Release_Group/Type|the documentation]]). This can be specified multiple times to select multiple secondary types, though only one primary type should be specified (if you specify more than one, only one will be set). |
|||
</blockquote> |
|||
; <code>comment</code> |
|||
: A disambiguation comment for the release. Non-empty string |
: A disambiguation comment for the release. Non-empty string |
||
; annotation |
; <code>annotation</code> |
||
: Text to place in the releases annotation |
: Text to place in the releases annotation. Use a text area / multi-line text |
||
; barcode |
; <code>barcode</code> |
||
: The barcode of the release. May be any valid barcode without whitespace |
: The barcode of the release. May be any valid barcode without whitespace. To indicate there is no barcode, seed "none". |
||
; <code>language</code> |
|||
; date.year |
|||
: The language of the release. May be any valid [[wikipedia:List_of_ISO_639-3_codes|ISO 639-3]] code (for example: <code>eng</code>, <code>deu</code>, <code>jpn</code>) |
|||
; date.month |
|||
; <code>script</code> |
|||
; date.day |
|||
: The script of the text on the release. May be any valid [[wikipedia:ISO_15924|ISO 15924]] code (for example: <code>Latn</code>, <code>Cyrl</code>) |
|||
: The date of the release. Each field is an integer |
|||
; <code>status</code> |
|||
; country |
|||
: The status of the release, as defined by MusicBrainz. Possible values: <code>official</code>, <code>promotion</code>, <code>bootleg</code>, <code>pseudo-release</code> |
|||
: The country the release was released in. May be any valid country ISO code (for example, GB, US, FR) |
|||
; <code>packaging</code> |
|||
; language |
|||
: The type of packaging of the release. The possible values are the names of the release group types, in English (see [[Release/Packaging|the documentation]]). |
|||
: The language of the release. May be any valid [http://en.wikipedia.org/wiki/List_of_ISO_639-2_codes ISO 639-2/T] code (for example, eng, deu, jpn) |
|||
; script |
|||
=== Release events === |
|||
: The script of the text on the release. May be any valid [http://en.wikipedia.org/wiki/ISO_15924 ISO 15924] code (for example, Latn, Cyrl) |
|||
; status |
|||
<blockquote> |
|||
: The status of the release, as defined by MusicBrainz. Possible values: official, promotion, bootleg, pseudo |
|||
A release can have zero, one or several release events. Each release event is composed of a date and a country. You must specify a positive integer for the <code>''x''</code> part of the field name to specify which release event referring to. For example: <code>events.''0''.date.year & events.''0''.country</code> or <code>events.''3''.date.year & events.''3''.date.month & events.''3''.date.day & events.''3''.country</code>. Any of the fields can be omitted or sent blank if unknown (so, you can seed only the year and country, or only the month and day). |
|||
; type |
|||
: The type of the release group, if a release group will be created. Possible values: album, single, ep, compilation, soundtrack, spokenword, interview, audiobook, live, remix, other (this can be specified multiple times to select multiple secondary types, though only one primary type should be specified). |
|||
; <code>events.''x''.date.year</code> |
|||
; packaging |
|||
; <code>events.''x''.date.month</code> |
|||
: The type of packaging of the release. Possible values: 'jewel case', 'slim jewel case', 'digipak', 'cardboard/paper sleeve', 'other', 'keep case' |
|||
; <code>events.''x''.date.day</code> |
|||
: The date of the release event. Each field is an integer |
|||
; <code>events.''x''.country</code> |
|||
: The country of the release event. May be any valid country ISO code (for example: <code>GB</code>, <code>US</code>, <code>FR</code>) |
|||
</blockquote> |
|||
=== Labels and catalog numbers === |
=== Labels and catalog numbers === |
||
<blockquote> |
|||
Releases may be associated with multiple labels and catalog numbers, so the fields for specifying these is a little different. You must specify a positive integer for the ''n'' part of the field name to specify which label/catalog number pair you are referring to. For example: label.0.mbid and label.0.catalog_number |
|||
Releases may be associated with multiple labels and catalog numbers, so the fields for specifying these are a little different. You must specify a positive integer for the <code>''x''</code> part of the field name to specify which label/catalog number pair you are referring to. For example: <code>label.''0''.mbid</code> and <code>label.''0''.catalog_number</code> |
|||
; labels.'' |
; <code>labels.''x''.mbid</code> |
||
: The MBID of the label |
: The MBID of the label |
||
; labels.'' |
; <code>labels.''x''.catalog_number</code> |
||
: The catalog number of this release, for label '' |
: The catalog number of this release, for label <code>''x''</code> |
||
; labels.'' |
; <code>labels.''x''.name</code> |
||
: The name of the label. If an MBID is present, this value is ignored |
: The name of the label (to prefill the field in order to search for the label via the site interface). If an MBID is present, this value is ignored |
||
</blockquote> |
|||
=== Artist credit === |
=== Artist credit === |
||
<blockquote> |
|||
A release may be credited to multiple artists via what is known as an "artist credit." To specify the artists a release is credited, you can use the following fields: |
|||
A release may be credited to multiple artists via what is known as an [[Artist Credit]]. To specify the artists a release is credited to, you can use the following fields: |
|||
; artist_credit.names.'' |
; <code>artist_credit.names.''x''.mbid</code> |
||
: The MBID of the artist. If omitted you will be able to either create the artist in the |
: The MBID of the artist. If omitted you will be able to either create the artist in the release editor, or search MusicBrainz for this artist |
||
; artist_credit.names.'' |
; <code>artist_credit.names.''x''.name</code> |
||
: The name of the artist, as credited on the release. Optional, if omitted it will default to the |
: The name of the artist, as credited on the release. Optional, if omitted it will default to the artist’s current name |
||
; artist_credit.names.'' |
; <code>artist_credit.names.''x''.artist.name</code> |
||
: The name of the artist as it is usually referred too. |
: The name of the artist as it is usually referred too (to prefill the field in order to search for the artist via the site interface). Unneeded if you already specified both credited name and MBID |
||
; artist_credit.names.'' |
; <code>artist_credit.names.''x''.join_phrase</code> |
||
: An optional phrase to join this artist with the next artist. For example, you could use |
: An optional phrase to join this artist with the next artist. For example, you could use “ & ” to join “Calvin” with “Hobbes” to get the final text “Calvin & Hobbes” |
||
</blockquote> |
|||
== Tracklists |
== Tracklists data == |
||
As with labels above, |
As with labels above, there may be multiple mediums and tracklists which themselves may contain multiple tracks, so again you will need to fill in the <code>''x''</code> and <code>''y''</code> parameters accordingly. As with others, <code>''x''</code> and <code>''y''</code> are 0-indexed. Values for <code>''x''</code> must be in consecutive order starting with <code>''0''</code>; with at least 1 track for each medium. |
||
=== Mediums === |
|||
; mediums.''n''.format |
|||
: Any valid medium format name: may be any one of '''auto generate me''' |
|||
; mediums.''n''.position |
|||
: The position of this medium in the list of mediums. If omitted, it will be inferred from the order of all mediums passed in (which is normally what you want). |
|||
; mediums.''n''.name |
|||
: The name of medium ''n'' (for example "Live & Unreleased") |
|||
; mediums.'' |
; <code>mediums.''x''.format</code> |
||
: Any valid medium format name. The possible values are the names of the medium formats, in English (see [[Release/Format|the documentation]], or check the release editor page’s source code) |
|||
: The name of track ''m'' on medium ''n'' |
|||
; <code>mediums.''x''.name</code> |
|||
: The name of medium <code>''x''</code> (for example “Live & Unreleased”) |
|||
==== Tracks ==== |
|||
; mediums.''n''.track.''m''.number |
|||
: The free-form track number of track ''m'' on medium ''n'' |
|||
<blockquote> |
|||
; mediums.''n''.track.''m''.artist_credit.names.''x''.mbid |
|||
; mediums.'' |
; <code>mediums.''x''.track.''y''.name</code> |
||
: The name of track <code>''y''</code> on medium <code>''x''</code> |
|||
; mediums.''n''.track.''m''.artist_credit.names.''x''.artist.name |
|||
; mediums.'' |
; <code>mediums.''x''.track.''y''.number</code> |
||
: The free-form track number of track <code>''y''</code> on medium <code>''x''</code> |
|||
: As like the [[#Artist_credit|release artist credit]], these parameters allow you to specify the artist credit for a track. Defaults to the release artist credit. |
|||
; mediums.'' |
; <code>mediums.''x''.track.''y''.recording</code> |
||
: The MBID of an existing recording in the database which should be associated with track <code>''y''</code> on medium <code>''x''</code> |
|||
: The tracks duration, in MM:SS form or a single integer as milliseconds |
|||
; <code>mediums.''x''.track.''y''.length</code> |
|||
: The tracks duration, in <code>MM:SS</code> form or a single integer as milliseconds |
|||
===== Track artist credits ===== |
|||
Refer to [[#Artist_credit|release artist credit]], as track artist credits share the same syntax. Here too you can have <code>''z''</code> artists (the first being <code>''0''</code> again). |
|||
; <code>mediums.''x''.track.''y''.artist_credit.names.''z''.mbid </code> |
|||
; <code>mediums.''x''.track.''y''.artist_credit.names.''z''.name </code> |
|||
; <code>mediums.''x''.track.''y''.artist_credit.names.''z''.artist.name </code> |
|||
; <code>mediums.''x''.track.''y''.artist_credit.names.''z''.join_phrase</code> |
|||
</blockquote> |
|||
== URL relationships == |
|||
You can seed a list of URLs to add as relationships to the release, using the following fields: |
|||
; <code>urls.''x''.url</code> |
|||
: The URL to relate to. Non-empty string. |
|||
; <code>urls.''x''.link_type</code> |
|||
: The integer link type ID to use for the relationship. Not required; if left blank, can be selected in the release editor. |
|||
== Other data == |
== Other data == |
||
; edit_note |
; <code>edit_note</code> |
||
: Specify the |
: Specify the content of the edit note. Use a text area / multi-line text |
||
; <code>redirect_uri</code> |
|||
: A URI to redirect to after the release is submitted. The release's MBID will be added to this URI under the 'release_mbid' query parameter. E.g., if 'http://example.com/' is provided for this, the user will be redirected to a URI like 'http://example.com/?release_mbid=4587fe99-db0e-4553-a56a-164dd38ab380' |
Latest revision as of 10:20, 5 October 2023
This page documents a list of parameters you can POST to the release editor to “seed” it. All values are optional unless otherwise stated.
To create a new release: http://musicbrainz.org/release/add
The MusicBrainz server includes an example which demonstrates seeding: seed-love-bug.html.
Release data
name
- The name of the release. Non-empty string. Required
Release group data
We can either re-use an existing release group with
release_group
- The MBID of an existing release group
Or we can create a new release group which will have the name of the release by listing its type(s)
type
- The type(s) of the release group that will be created. The possible values are the names of the release group types, in English (see the documentation). This can be specified multiple times to select multiple secondary types, though only one primary type should be specified (if you specify more than one, only one will be set).
comment
- A disambiguation comment for the release. Non-empty string
annotation
- Text to place in the releases annotation. Use a text area / multi-line text
barcode
- The barcode of the release. May be any valid barcode without whitespace. To indicate there is no barcode, seed "none".
language
- The language of the release. May be any valid ISO 639-3 code (for example:
eng
,deu
,jpn
) script
- The script of the text on the release. May be any valid ISO 15924 code (for example:
Latn
,Cyrl
) status
- The status of the release, as defined by MusicBrainz. Possible values:
official
,promotion
,bootleg
,pseudo-release
packaging
- The type of packaging of the release. The possible values are the names of the release group types, in English (see the documentation).
Release events
A release can have zero, one or several release events. Each release event is composed of a date and a country. You must specify a positive integer for the
x
part of the field name to specify which release event referring to. For example:events.0.date.year & events.0.country
orevents.3.date.year & events.3.date.month & events.3.date.day & events.3.country
. Any of the fields can be omitted or sent blank if unknown (so, you can seed only the year and country, or only the month and day).
events.x.date.year
events.x.date.month
events.x.date.day
- The date of the release event. Each field is an integer
events.x.country
- The country of the release event. May be any valid country ISO code (for example:
GB
,US
,FR
)
Labels and catalog numbers
Releases may be associated with multiple labels and catalog numbers, so the fields for specifying these are a little different. You must specify a positive integer for the
x
part of the field name to specify which label/catalog number pair you are referring to. For example:label.0.mbid
andlabel.0.catalog_number
labels.x.mbid
- The MBID of the label
labels.x.catalog_number
- The catalog number of this release, for label
x
labels.x.name
- The name of the label (to prefill the field in order to search for the label via the site interface). If an MBID is present, this value is ignored
Artist credit
A release may be credited to multiple artists via what is known as an Artist Credit. To specify the artists a release is credited to, you can use the following fields:
artist_credit.names.x.mbid
- The MBID of the artist. If omitted you will be able to either create the artist in the release editor, or search MusicBrainz for this artist
artist_credit.names.x.name
- The name of the artist, as credited on the release. Optional, if omitted it will default to the artist’s current name
artist_credit.names.x.artist.name
- The name of the artist as it is usually referred too (to prefill the field in order to search for the artist via the site interface). Unneeded if you already specified both credited name and MBID
artist_credit.names.x.join_phrase
- An optional phrase to join this artist with the next artist. For example, you could use “ & ” to join “Calvin” with “Hobbes” to get the final text “Calvin & Hobbes”
Tracklists data
As with labels above, there may be multiple mediums and tracklists which themselves may contain multiple tracks, so again you will need to fill in the x
and y
parameters accordingly. As with others, x
and y
are 0-indexed. Values for x
must be in consecutive order starting with 0
; with at least 1 track for each medium.
Mediums
mediums.x.format
- Any valid medium format name. The possible values are the names of the medium formats, in English (see the documentation, or check the release editor page’s source code)
mediums.x.name
- The name of medium
x
(for example “Live & Unreleased”)
Tracks
mediums.x.track.y.name
- The name of track
y
on mediumx
mediums.x.track.y.number
- The free-form track number of track
y
on mediumx
mediums.x.track.y.recording
- The MBID of an existing recording in the database which should be associated with track
y
on mediumx
mediums.x.track.y.length
- The tracks duration, in
MM:SS
form or a single integer as millisecondsTrack artist credits
Refer to release artist credit, as track artist credits share the same syntax. Here too you can have
z
artists (the first being0
again).
mediums.x.track.y.artist_credit.names.z.mbid
mediums.x.track.y.artist_credit.names.z.name
mediums.x.track.y.artist_credit.names.z.artist.name
mediums.x.track.y.artist_credit.names.z.join_phrase
URL relationships
You can seed a list of URLs to add as relationships to the release, using the following fields:
urls.x.url
- The URL to relate to. Non-empty string.
urls.x.link_type
- The integer link type ID to use for the relationship. Not required; if left blank, can be selected in the release editor.
Other data
edit_note
- Specify the content of the edit note. Use a text area / multi-line text
redirect_uri
- A URI to redirect to after the release is submitted. The release's MBID will be added to this URI under the 'release_mbid' query parameter. E.g., if 'http://example.com/' is provided for this, the user will be redirected to a URI like 'http://example.com/?release_mbid=4587fe99-db0e-4553-a56a-164dd38ab380'