musicbrainz-api 0.10.2 → 0.11.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +481 -476
- package/lib/digest-auth.d.ts +2 -2
- package/lib/digest-auth.js +6 -6
- package/lib/musicbrainz-api.d.ts +12 -14
- package/lib/musicbrainz-api.js +15 -12
- package/lib/musicbrainz.types.d.ts +7 -1
- package/lib/rate-limiter.d.ts +1 -1
- package/lib/rate-limiter.js +2 -2
- package/lib/xml/xml-isrc-list.d.ts +1 -1
- package/lib/xml/xml-recording.d.ts +2 -2
- package/package.json +108 -104
- package/.idea/$CACHE_FILE$ +0 -6
- package/.idea/$PRODUCT_WORKSPACE_FILE$ +0 -19
- package/.idea/jpa-buddy.xml +0 -6
- package/.idea/misc.xml +0 -12
- package/.idea/modules.xml +0 -8
- package/.idea/vcs.xml +0 -11
package/README.md
CHANGED
|
@@ -1,476 +1,481 @@
|
|
|
1
|
-
[](https://github.com/Borewit/musicbrainz-api/actions/workflows/nodejs-ci.yml)
|
|
2
|
-
[](https://npmjs.org/package/musicbrainz-api)
|
|
3
|
-
[](https://npmcharts.com/compare/musicbrainz-api)
|
|
4
|
-
[](https://coveralls.io/github/Borewit/musicbrainz-api?branch=master)
|
|
5
|
-
[](https://www.codacy.com/gh/Borewit/musicbrainz-api/dashboard?utm_source=github.com&utm_medium=referral&utm_content=Borewit/musicbrainz-api&utm_campaign=Badge_Grade)
|
|
6
|
-
[](https://github.com/Borewit/musicbrainz-api/actions/workflows/codeql.yml)
|
|
7
|
-
[](https://snyk.io/test/github/Borewit/musicbrainz-api?targetFile=package.json)
|
|
8
|
-
[](https://deepscan.io/dashboard#view=project&tid=5165&pid=6991&bid=63373)
|
|
9
|
-
[](https://discord.gg/958xT5X)
|
|
10
|
-
|
|
11
|
-
# musicbrainz-api
|
|
12
|
-
|
|
13
|
-
A MusicBrainz-API-client for reading and submitting metadata
|
|
14
|
-
|
|
15
|
-
## Features
|
|
16
|
-
* Access metadata from MusicBrainz
|
|
17
|
-
* Submit metadata
|
|
18
|
-
* Smart and adjustable throttling, like MusicBrainz, it allows a bursts of requests
|
|
19
|
-
* Build in TypeScript definitions
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
##
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
```js
|
|
137
|
-
const
|
|
138
|
-
```
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
```
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
```js
|
|
149
|
-
const
|
|
150
|
-
```
|
|
151
|
-
|
|
152
|
-
### Lookup release
|
|
153
|
-
```js
|
|
154
|
-
const
|
|
155
|
-
```
|
|
156
|
-
|
|
157
|
-
### Lookup
|
|
158
|
-
```js
|
|
159
|
-
const
|
|
160
|
-
```
|
|
161
|
-
|
|
162
|
-
### Lookup
|
|
163
|
-
```js
|
|
164
|
-
const
|
|
165
|
-
```
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
|
191
|
-
|
|
192
|
-
| `query.
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
|
205
|
-
|
|
206
|
-
| `query.
|
|
207
|
-
| `query.
|
|
208
|
-
| `query.
|
|
209
|
-
| `query.
|
|
210
|
-
| `query.
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
|
277
|
-
|
|
278
|
-
| `query.
|
|
279
|
-
| `query.
|
|
280
|
-
| `query.
|
|
281
|
-
| `query.
|
|
282
|
-
| `query.
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
|
|
|
306
|
-
|
|
307
|
-
| `query.
|
|
308
|
-
| `query.
|
|
309
|
-
| `query.
|
|
310
|
-
| `query.
|
|
311
|
-
| `query.
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
|
|
315
|
-
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
|
|
321
|
-
|
|
322
|
-
|
|
323
|
-
|
|
324
|
-
|
|
325
|
-
|
|
326
|
-
|
|
327
|
-
|
|
328
|
-
|
|
329
|
-
|
|
330
|
-
|
|
331
|
-
|
|
332
|
-
|
|
333
|
-
|
|
334
|
-
|
|
335
|
-
|
|
336
|
-
|
|
337
|
-
|
|
338
|
-
|
|
339
|
-
|
|
340
|
-
|
|
341
|
-
|
|
342
|
-
|
|
343
|
-
|
|
344
|
-
|
|
345
|
-
|
|
346
|
-
|
|
347
|
-
|
|
348
|
-
|
|
349
|
-
|
|
350
|
-
* `
|
|
351
|
-
* `
|
|
352
|
-
* `
|
|
353
|
-
* `
|
|
354
|
-
* `
|
|
355
|
-
* `
|
|
356
|
-
* `
|
|
357
|
-
|
|
358
|
-
|
|
359
|
-
|
|
360
|
-
|
|
361
|
-
|
|
362
|
-
|
|
363
|
-
|
|
364
|
-
|
|
365
|
-
|
|
366
|
-
|
|
367
|
-
|
|
368
|
-
|
|
369
|
-
|
|
370
|
-
|
|
371
|
-
|
|
372
|
-
|
|
373
|
-
|
|
374
|
-
|
|
375
|
-
|
|
376
|
-
|
|
377
|
-
|
|
378
|
-
|
|
379
|
-
|
|
380
|
-
|
|
381
|
-
|
|
382
|
-
|
|
383
|
-
|
|
384
|
-
|
|
385
|
-
|
|
386
|
-
|
|
387
|
-
|
|
388
|
-
|
|
389
|
-
|
|
390
|
-
|
|
391
|
-
|
|
392
|
-
|
|
393
|
-
|
|
394
|
-
|
|
395
|
-
```
|
|
396
|
-
|
|
397
|
-
Search
|
|
398
|
-
```js
|
|
399
|
-
const result = await mbApi.
|
|
400
|
-
```
|
|
401
|
-
|
|
402
|
-
Search
|
|
403
|
-
```js
|
|
404
|
-
const result = await mbApi.searchReleaseGroup({
|
|
405
|
-
```
|
|
406
|
-
|
|
407
|
-
|
|
408
|
-
|
|
409
|
-
|
|
410
|
-
|
|
411
|
-
|
|
412
|
-
|
|
413
|
-
|
|
414
|
-
|
|
415
|
-
|
|
416
|
-
|
|
417
|
-
|
|
418
|
-
|
|
419
|
-
|
|
420
|
-
|
|
421
|
-
|
|
422
|
-
|
|
423
|
-
|
|
424
|
-
|
|
425
|
-
|
|
426
|
-
|
|
427
|
-
|
|
428
|
-
|
|
429
|
-
|
|
430
|
-
|
|
431
|
-
|
|
432
|
-
|
|
433
|
-
|
|
434
|
-
|
|
435
|
-
|
|
436
|
-
|
|
437
|
-
|
|
438
|
-
|
|
439
|
-
|
|
440
|
-
|
|
441
|
-
|
|
442
|
-
|
|
443
|
-
|
|
444
|
-
|
|
445
|
-
|
|
446
|
-
|
|
447
|
-
|
|
448
|
-
|
|
449
|
-
|
|
450
|
-
|
|
451
|
-
|
|
452
|
-
|
|
453
|
-
|
|
454
|
-
|
|
455
|
-
|
|
456
|
-
|
|
457
|
-
|
|
458
|
-
await mbApi.
|
|
459
|
-
|
|
460
|
-
|
|
461
|
-
|
|
462
|
-
|
|
463
|
-
|
|
464
|
-
|
|
465
|
-
|
|
466
|
-
|
|
467
|
-
|
|
468
|
-
|
|
469
|
-
|
|
470
|
-
|
|
471
|
-
|
|
472
|
-
|
|
473
|
-
|
|
474
|
-
|
|
475
|
-
|
|
476
|
-
|
|
1
|
+
[](https://github.com/Borewit/musicbrainz-api/actions/workflows/nodejs-ci.yml)
|
|
2
|
+
[](https://npmjs.org/package/musicbrainz-api)
|
|
3
|
+
[](https://npmcharts.com/compare/musicbrainz-api?interval=30&start=365)
|
|
4
|
+
[](https://coveralls.io/github/Borewit/musicbrainz-api?branch=master)
|
|
5
|
+
[](https://www.codacy.com/gh/Borewit/musicbrainz-api/dashboard?utm_source=github.com&utm_medium=referral&utm_content=Borewit/musicbrainz-api&utm_campaign=Badge_Grade)
|
|
6
|
+
[](https://github.com/Borewit/musicbrainz-api/actions/workflows/codeql.yml)
|
|
7
|
+
[](https://snyk.io/test/github/Borewit/musicbrainz-api?targetFile=package.json)
|
|
8
|
+
[](https://deepscan.io/dashboard#view=project&tid=5165&pid=6991&bid=63373)
|
|
9
|
+
[](https://discord.gg/958xT5X)
|
|
10
|
+
|
|
11
|
+
# musicbrainz-api
|
|
12
|
+
|
|
13
|
+
A MusicBrainz-API-client for reading and submitting metadata
|
|
14
|
+
|
|
15
|
+
## Features
|
|
16
|
+
* Access metadata from MusicBrainz
|
|
17
|
+
* Submit metadata
|
|
18
|
+
* Smart and adjustable throttling, like MusicBrainz, it allows a bursts of requests
|
|
19
|
+
* Build in TypeScript definitions
|
|
20
|
+
|
|
21
|
+
### Hint
|
|
22
|
+
|
|
23
|
+
This package is currently only developed for the use in a [node.js environment](http://nodejs.org/).
|
|
24
|
+
We are looking into making this package usable in the browser as well.
|
|
25
|
+
|
|
26
|
+
## Before using this library
|
|
27
|
+
|
|
28
|
+
MusicBrainz asks that you to [identify your application](https://wiki.musicbrainz.org/Development/XML_Web_Service/Version_2#User%20Data) by filling in the ['User-Agent' Header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent).
|
|
29
|
+
By passing `appName`, `appVersion`, `appMail` musicbrainz-api takes care of that.
|
|
30
|
+
|
|
31
|
+
## Submitting metadata
|
|
32
|
+
|
|
33
|
+
If you plan to use this module for submitting metadata, please ensure you comply with [the MusicBrainz Code of conduct/Bots](https://wiki.musicbrainz.org/Code_of_Conduct/Bots).
|
|
34
|
+
|
|
35
|
+
## Example
|
|
36
|
+
|
|
37
|
+
Import the module
|
|
38
|
+
JavaScript example, how to import 'musicbrainz-api:
|
|
39
|
+
```js
|
|
40
|
+
const MusicBrainzApi = require('musicbrainz-api').MusicBrainzApi;
|
|
41
|
+
|
|
42
|
+
const mbApi = new MusicBrainzApi({
|
|
43
|
+
appName: 'my-app',
|
|
44
|
+
appVersion: '0.1.0',
|
|
45
|
+
appContactInfo: 'user@mail.org'
|
|
46
|
+
});
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
In TypeScript it would look like this:
|
|
50
|
+
```js
|
|
51
|
+
import {MusicBrainzApi} from 'musicbrainz-api';
|
|
52
|
+
|
|
53
|
+
const mbApi = new MusicBrainzApi({
|
|
54
|
+
appName: 'my-app',
|
|
55
|
+
appVersion: '0.1.0',
|
|
56
|
+
appContactInfo: 'user@mail.org' // Or URL to application home page
|
|
57
|
+
});
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
The following configuration settings can be passed
|
|
61
|
+
```js
|
|
62
|
+
import {MusicBrainzApi} from '../src/musicbrainz-api';
|
|
63
|
+
|
|
64
|
+
const config = {
|
|
65
|
+
// MusicBrainz bot account username & password (optional)
|
|
66
|
+
botAccount: {
|
|
67
|
+
username: 'myUserName_bot',
|
|
68
|
+
password: 'myPassword'
|
|
69
|
+
},
|
|
70
|
+
|
|
71
|
+
// API base URL, default: 'https://musicbrainz.org' (optional)
|
|
72
|
+
baseUrl: 'https://musicbrainz.org',
|
|
73
|
+
|
|
74
|
+
appName: 'my-app',
|
|
75
|
+
appVersion: '0.1.0',
|
|
76
|
+
|
|
77
|
+
// Optional, default: no proxy server
|
|
78
|
+
proxy: {
|
|
79
|
+
host: 'localhost',
|
|
80
|
+
port: 8888
|
|
81
|
+
},
|
|
82
|
+
|
|
83
|
+
// Your e-mail address, required for submitting ISRCs
|
|
84
|
+
appMail: string
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
const mbApi = new MusicbrainzApi(config);
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
## Lookup MusicBrainz Entities
|
|
91
|
+
|
|
92
|
+
MusicBrainz API documentation: [XML Web Service/Version 2 Lookups](https://wiki.musicbrainz.org/Development/XML_Web_Service/Version_2#Lookups)
|
|
93
|
+
|
|
94
|
+
### Generic lookup function
|
|
95
|
+
|
|
96
|
+
Arguments:
|
|
97
|
+
* entity: `'artist'` | `'label'` | `'recording'` | `'release'` | `'release-group'` | `'work'` | `'area'` | `'url'`
|
|
98
|
+
* MBID [(MusicBrainz identifier)](https://wiki.musicbrainz.org/MusicBrainz_Identifier)
|
|
99
|
+
|
|
100
|
+
```js
|
|
101
|
+
const artist = await mbApi.lookupEntity('artist', 'ab2528d9-719f-4261-8098-21849222a0f2');
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
### Lookup area
|
|
105
|
+
|
|
106
|
+
```js
|
|
107
|
+
const area = await mbApi.lookupArea('ab2528d9-719f-4261-8098-21849222a0f2');
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
### Lookup artist
|
|
111
|
+
|
|
112
|
+
Lookup an `artist` and include their `releases`, `release-groups` and `aliases`
|
|
113
|
+
|
|
114
|
+
```js
|
|
115
|
+
const artist = await mbApi.lookupArtist('ab2528d9-719f-4261-8098-21849222a0f2');
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
### Lookup instrument
|
|
119
|
+
|
|
120
|
+
Lookup an instrument
|
|
121
|
+
|
|
122
|
+
```js
|
|
123
|
+
const instrument = await mbApi.lookupInstrument('b3eac5f9-7859-4416-ac39-7154e2e8d348');
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
### Lookup label
|
|
127
|
+
|
|
128
|
+
Lookup a label
|
|
129
|
+
|
|
130
|
+
```js
|
|
131
|
+
const label = await mbApi.lookupLabel('25dda9f9-f069-4898-82f0-59330a106c7f');
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
### Lookup place
|
|
135
|
+
|
|
136
|
+
```js
|
|
137
|
+
const place = await mbApi.lookupPlace('e6cfb74d-d69b-44c3-b890-1b3f509816e4');
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
The second argument can be used to pass [subqueries](https://wiki.musicbrainz.org/Development/XML_Web_Service/Version_2#Subqueries), which will return more (nested) information:
|
|
141
|
+
```js
|
|
142
|
+
const artist = await mbApi.lookupArtist('ab2528d9-719f-4261-8098-21849222a0f2', ['releases', 'recordings', 'url-rels']);
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
### Lookup recording
|
|
146
|
+
|
|
147
|
+
The second argument can be used to pass [subqueries](https://wiki.musicbrainz.org/Development/XML_Web_Service/Version_2#Subqueries):
|
|
148
|
+
```js
|
|
149
|
+
const recording = await mbApi.lookupRecording('16afa384-174e-435e-bfa3-5591accda31c', ['artists', 'url-rels']);
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
### Lookup release
|
|
153
|
+
```js
|
|
154
|
+
const release = await mbApi.lookupRelease('976e0677-a480-4a5e-a177-6a86c1900bbf', ['artists', 'url-rels']);
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
### Lookup release-group
|
|
158
|
+
```js
|
|
159
|
+
const releaseGroup = await mbApi.lookupReleaseGroup('19099ea5-3600-4154-b482-2ec68815883e');
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
### Lookup work
|
|
163
|
+
```js
|
|
164
|
+
const work = await mbApi.lookupWork('b2aa02f4-6c95-43be-a426-aedb9f9a3805');
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
### Lookup URL
|
|
168
|
+
```js
|
|
169
|
+
const url = await mbApi.lookupUrl('c69556a6-7ded-4c54-809c-afb45a1abe7d');
|
|
170
|
+
```
|
|
171
|
+
|
|
172
|
+
## Browse entities
|
|
173
|
+
|
|
174
|
+
### Browse area
|
|
175
|
+
|
|
176
|
+
```js
|
|
177
|
+
const area = await browseAreas(query);
|
|
178
|
+
````
|
|
179
|
+
|
|
180
|
+
| Query argument | Query value |
|
|
181
|
+
|-----------------------|-----------------|
|
|
182
|
+
| `query.collection` | Collection MBID |
|
|
183
|
+
|
|
184
|
+
### Browse artist
|
|
185
|
+
|
|
186
|
+
```js
|
|
187
|
+
const artist = await browseArtist(query);
|
|
188
|
+
````
|
|
189
|
+
|
|
190
|
+
| Query argument | Query value |
|
|
191
|
+
|-----------------------|--------------------|
|
|
192
|
+
| `query.area` | Area MBID |
|
|
193
|
+
| `query.collection` | Collection MBID |
|
|
194
|
+
| `query.recording` | Recording MBID |
|
|
195
|
+
| `query.release` | Release MBID |
|
|
196
|
+
| `query.release-group` | Release-group MBID |
|
|
197
|
+
| `query.work` | Work MBID |
|
|
198
|
+
|
|
199
|
+
### Browse collection
|
|
200
|
+
```js
|
|
201
|
+
const artist = await browseCollection(query);
|
|
202
|
+
````
|
|
203
|
+
|
|
204
|
+
| Query argument | Query value |
|
|
205
|
+
|-----------------------|--------------------|
|
|
206
|
+
| `query.area` | Area MBID |
|
|
207
|
+
| `query.artist` | Artist MBID |
|
|
208
|
+
| `query.editor` | Editor MBID |
|
|
209
|
+
| `query.event` | Event MBID |
|
|
210
|
+
| `query.label` | Label MBID |
|
|
211
|
+
| `query.place` | Place MBID |
|
|
212
|
+
| `query.recording` | Recording MBID |
|
|
213
|
+
| `query.release` | Release MBID |
|
|
214
|
+
| `query.release-group` | Release-group MBID |
|
|
215
|
+
| `query.work` | Work MBID |
|
|
216
|
+
|
|
217
|
+
### Browse events
|
|
218
|
+
```js
|
|
219
|
+
const events = await browseEvents(query);
|
|
220
|
+
````
|
|
221
|
+
|
|
222
|
+
| Query argument | Query value |
|
|
223
|
+
|-----------------------|-----------------|
|
|
224
|
+
| `query.area` | Area MBID |
|
|
225
|
+
| `query.artist` | Artist MBID |
|
|
226
|
+
| `query.collection` | Collection MBID |
|
|
227
|
+
| `query.place` | Place MBID |
|
|
228
|
+
|
|
229
|
+
### Browse instruments
|
|
230
|
+
```js
|
|
231
|
+
const instruments = await browseEvents(query);
|
|
232
|
+
````
|
|
233
|
+
|
|
234
|
+
| Query argument | Query value |
|
|
235
|
+
|-----------------------|--------------------|
|
|
236
|
+
| `query.collection` | Collection MBID |
|
|
237
|
+
|
|
238
|
+
### Browse labels
|
|
239
|
+
```js
|
|
240
|
+
const labels = await browseLabels(query);
|
|
241
|
+
````
|
|
242
|
+
|
|
243
|
+
| Query argument | Query value |
|
|
244
|
+
|--------------------|-----------------|
|
|
245
|
+
| `query.area` | Area MBID |
|
|
246
|
+
| `query.collection` | Collection MBID |
|
|
247
|
+
| `query.release` | Release MBID |
|
|
248
|
+
|
|
249
|
+
### Browse places
|
|
250
|
+
```js
|
|
251
|
+
const places = await browsePlaces(query);
|
|
252
|
+
````
|
|
253
|
+
|
|
254
|
+
| Query argument | Query value |
|
|
255
|
+
|--------------------|-----------------|
|
|
256
|
+
| `query.area` | Area MBID |
|
|
257
|
+
| `query.collection` | Collection MBID |
|
|
258
|
+
|
|
259
|
+
### Browse recordings
|
|
260
|
+
```js
|
|
261
|
+
const recordings = await browseRecordings(query);
|
|
262
|
+
````
|
|
263
|
+
|
|
264
|
+
| Query argument | Query value |
|
|
265
|
+
|--------------------|-----------------|
|
|
266
|
+
| `query.artist` | Area MBID |
|
|
267
|
+
| `query.collection` | Collection MBID |
|
|
268
|
+
| `query.release` | Release MBID |
|
|
269
|
+
| `query.work` | Work MBID |
|
|
270
|
+
|
|
271
|
+
### Browse releases
|
|
272
|
+
```js
|
|
273
|
+
const places = await browseReleases(query);
|
|
274
|
+
````
|
|
275
|
+
|
|
276
|
+
| Query argument | Query value |
|
|
277
|
+
|-----------------------|--------------------|
|
|
278
|
+
| `query.area` | Area MBID |
|
|
279
|
+
| `query.artist` | Artist MBID |
|
|
280
|
+
| `query.editor` | Editor MBID |
|
|
281
|
+
| `query.event` | Event MBID |
|
|
282
|
+
| `query.label` | Label MBID |
|
|
283
|
+
| `query.place` | Place MBID |
|
|
284
|
+
| `query.recording` | Recording MBID |
|
|
285
|
+
| `query.release` | Release MBID |
|
|
286
|
+
| `query.release-group` | Release-group MBID |
|
|
287
|
+
| `query.work` | Work MBID |
|
|
288
|
+
|
|
289
|
+
### Browse release-groups
|
|
290
|
+
```js
|
|
291
|
+
const places = await browseReleaseGroups(query);
|
|
292
|
+
```
|
|
293
|
+
|
|
294
|
+
| Query argument | Query value |
|
|
295
|
+
|--------------------|-----------------|
|
|
296
|
+
| `query.artist` | Artist MBID |
|
|
297
|
+
| `query.collection` | Collection MBID |
|
|
298
|
+
| `query.release` | Release MBID |
|
|
299
|
+
|
|
300
|
+
### Browse series
|
|
301
|
+
```js
|
|
302
|
+
const places = await browseSeries();
|
|
303
|
+
````
|
|
304
|
+
|
|
305
|
+
| Query argument | Query value |
|
|
306
|
+
|-----------------------|--------------------|
|
|
307
|
+
| `query.area` | Area MBID |
|
|
308
|
+
| `query.artist` | Artist MBID |
|
|
309
|
+
| `query.editor` | Editor MBID |
|
|
310
|
+
| `query.event` | Event MBID |
|
|
311
|
+
| `query.label` | Label MBID |
|
|
312
|
+
| `query.place` | Place MBID |
|
|
313
|
+
| `query.recording` | Recording MBID |
|
|
314
|
+
| `query.release` | Release MBID |
|
|
315
|
+
| `query.release-group` | Release-group MBID |
|
|
316
|
+
| `query.work` | Work MBID |
|
|
317
|
+
|
|
318
|
+
### Browse works
|
|
319
|
+
```js
|
|
320
|
+
const places = await browseWorks();
|
|
321
|
+
````
|
|
322
|
+
|
|
323
|
+
| Query argument | Query value |
|
|
324
|
+
|--------------------|-----------------|
|
|
325
|
+
| `query.artist` | Artist MBID |
|
|
326
|
+
| `query.xollection` | Collection MBID |
|
|
327
|
+
|
|
328
|
+
### Browse urls
|
|
329
|
+
```js
|
|
330
|
+
const urls = await browseUrls();
|
|
331
|
+
````
|
|
332
|
+
|
|
333
|
+
| Query argument | Query value |
|
|
334
|
+
|--------------------|-----------------|
|
|
335
|
+
| `query.artist` | Artist MBID |
|
|
336
|
+
| `query.xollection` | Collection MBID |
|
|
337
|
+
|
|
338
|
+
## Search (query)
|
|
339
|
+
|
|
340
|
+
Implements [XML Web Service/Version 2/Search](https://wiki.musicbrainz.org/Development/XML_Web_Service/Version_2/Search).
|
|
341
|
+
|
|
342
|
+
There are different search fields depending on the entity.
|
|
343
|
+
|
|
344
|
+
### Generic search function
|
|
345
|
+
|
|
346
|
+
Searches can be performed using the generic search function: `query(entity: mb.EntityType, query: string | IFormData, offset?: number, limit?: number)`
|
|
347
|
+
|
|
348
|
+
Arguments:
|
|
349
|
+
* Entity type, which can be one of:
|
|
350
|
+
* `artist`: [search fields](https://wiki.musicbrainz.org/Development/XML_Web_Service/Version_2/Search#Artist)
|
|
351
|
+
* `label`: [search fields](https://wiki.musicbrainz.org/Development/XML_Web_Service/Version_2/Search#Label)
|
|
352
|
+
* `recording`: [search fields](https://wiki.musicbrainz.org/Development/XML_Web_Service/Version_2/Search#Recording)
|
|
353
|
+
* `release`: [search fields](https://wiki.musicbrainz.org/Development/XML_Web_Service/Version_2/Search#Release)
|
|
354
|
+
* `release-group`: [search fields](https://wiki.musicbrainz.org/Development/XML_Web_Service/Version_2/Search#Release_Group)
|
|
355
|
+
* `work`: [search fields](https://wiki.musicbrainz.org/Development/XML_Web_Service/Version_2/Search#Work)
|
|
356
|
+
* `area`: [search fields](https://wiki.musicbrainz.org/Development/XML_Web_Service/Version_2/Search#Area)
|
|
357
|
+
* `url`: [search fields](https://wiki.musicbrainz.org/Development/XML_Web_Service/Version_2/Search#URL)
|
|
358
|
+
* `query {query: string, offset: number, limit: number}`
|
|
359
|
+
* `query.query`: supports the full Lucene Search syntax; you can find a detailed guide at [Lucene Search Syntax](https://lucene.apache.org/core/4_3_0/queryparser/org/apache/lucene/queryparser/classic/package-summary.html#package_description). For example, you can set conditions while searching for a name with the AND operator.
|
|
360
|
+
* `query.offset`: optional, return search results starting at a given offset. Used for paging through more than one page of results.
|
|
361
|
+
* `limit.query`: optional, an integer value defining how many entries should be returned. Only values between 1 and 100 (both inclusive) are allowed. If not given, this defaults to 25.
|
|
362
|
+
|
|
363
|
+
For example, to find any recordings of _'We Will Rock You'_ by Queen:
|
|
364
|
+
```js
|
|
365
|
+
const query = 'query="We Will Rock You" AND arid:0383dadf-2a4e-4d10-a46a-e9e041da8eb3';
|
|
366
|
+
const result = await mbApi.query<mb.IReleaseGroupList>('release-group', {query});
|
|
367
|
+
```
|
|
368
|
+
|
|
369
|
+
##### Example: search Île-de-France
|
|
370
|
+
|
|
371
|
+
```js
|
|
372
|
+
mbApi.search('area', 'Île-de-France');
|
|
373
|
+
````
|
|
374
|
+
|
|
375
|
+
##### Example: search release by barcode
|
|
376
|
+
|
|
377
|
+
Search a release with the barcode 602537479870:
|
|
378
|
+
```js
|
|
379
|
+
mbApi.search('release', {query: {barcode: 602537479870}});
|
|
380
|
+
````
|
|
381
|
+
|
|
382
|
+
##### Example: search by object
|
|
383
|
+
|
|
384
|
+
Same as previous example, but automatically serialize parameters to search query
|
|
385
|
+
```js
|
|
386
|
+
mbApi.search('release', 'barcode: 602537479870');
|
|
387
|
+
````
|
|
388
|
+
|
|
389
|
+
### Entity specific search functions
|
|
390
|
+
|
|
391
|
+
The following entity specific search functions are available:
|
|
392
|
+
```TypeScript
|
|
393
|
+
searchArtist(query: string | IFormData, offset?: number, limit?: number): Promise<mb.IArtistList>
|
|
394
|
+
searchReleaseGroup(query: string | IFormData, offset?: number, limit?: number): Promise<mb.IReleaseGroupList>`
|
|
395
|
+
```
|
|
396
|
+
|
|
397
|
+
Search artist:
|
|
398
|
+
```js
|
|
399
|
+
const result = await mbApi.searchArtist({query: 'Stromae'});
|
|
400
|
+
```
|
|
401
|
+
|
|
402
|
+
Search release-group:
|
|
403
|
+
```js
|
|
404
|
+
const result = await mbApi.searchReleaseGroup({query: 'Racine carrée'});
|
|
405
|
+
```
|
|
406
|
+
|
|
407
|
+
Search a combination of a release-group and an artist.
|
|
408
|
+
```js
|
|
409
|
+
const result = await mbApi.searchReleaseGroup({artist: 'Racine carrée', releasegroup: 'Stromae'});
|
|
410
|
+
```
|
|
411
|
+
|
|
412
|
+
# Submitting data via XML POST
|
|
413
|
+
|
|
414
|
+
[Submitting data via XML POST](https://wiki.musicbrainz.org/Development/XML_Web_Service/Version_2#Submitting_data) may be done using personal MusicBrainz credentials.
|
|
415
|
+
|
|
416
|
+
## Submit ISRC code using XML POST
|
|
417
|
+
|
|
418
|
+
Using the [XML ISRC submission](https://wiki.musicbrainz.org/Development/XML_Web_Service/Version_2#ISRC_submission) API.
|
|
419
|
+
|
|
420
|
+
```js
|
|
421
|
+
const mbid_Formidable = '16afa384-174e-435e-bfa3-5591accda31c';
|
|
422
|
+
const isrc_Formidable = 'BET671300161';
|
|
423
|
+
|
|
424
|
+
const xmlMetadata = new XmlMetadata();
|
|
425
|
+
const xmlRecording = xmlMetadata.pushRecording(mbid_Formidable);
|
|
426
|
+
xmlRecording.isrcList.pushIsrc(isrc_Formidable);
|
|
427
|
+
await mbApi.post('recording', xmlMetadata);
|
|
428
|
+
```
|
|
429
|
+
|
|
430
|
+
# Submitting data via user form-data
|
|
431
|
+
|
|
432
|
+
For all of the following function you need to use a dedicated bot account.
|
|
433
|
+
|
|
434
|
+
## Submitting ISRC via post user form-data
|
|
435
|
+
|
|
436
|
+
<img width="150" src="http://www.clker.com/cliparts/i/w/L/q/u/1/work-in-progress.svg"/>
|
|
437
|
+
Use with caution, and only on a test server, it may clear existing metadata as side effect.
|
|
438
|
+
|
|
439
|
+
```js
|
|
440
|
+
|
|
441
|
+
const mbid_Formidable = '16afa384-174e-435e-bfa3-5591accda31c';
|
|
442
|
+
const isrc_Formidable = 'BET671300161';
|
|
443
|
+
|
|
444
|
+
|
|
445
|
+
const recording = await mbApi.lookupRecording(mbid_Formidable);
|
|
446
|
+
|
|
447
|
+
// Authentication the http-session against MusicBrainz (as defined in config.baseUrl)
|
|
448
|
+
const succeed = await mbApi.login();
|
|
449
|
+
assert.isTrue(succeed, 'Login successful');
|
|
450
|
+
|
|
451
|
+
// To submit the ISRC, the `recording.id` and `recording.title` are required
|
|
452
|
+
await mbApi.addIsrc(recording, isrc_Formidable);
|
|
453
|
+
```
|
|
454
|
+
|
|
455
|
+
### Submit recording URL
|
|
456
|
+
|
|
457
|
+
```js
|
|
458
|
+
const recording = await mbApi.lookupRecording('16afa384-174e-435e-bfa3-5591accda31c');
|
|
459
|
+
|
|
460
|
+
const succeed = await mbApi.login();
|
|
461
|
+
assert.isTrue(succeed, 'Login successful');
|
|
462
|
+
|
|
463
|
+
await mbApi.addUrlToRecording(recording, {
|
|
464
|
+
linkTypeId: LinkType.stream_for_free,
|
|
465
|
+
text: 'https://open.spotify.com/track/2AMysGXOe0zzZJMtH3Nizb'
|
|
466
|
+
});
|
|
467
|
+
```
|
|
468
|
+
|
|
469
|
+
Actually a Spotify-track-ID can be submitted easier:
|
|
470
|
+
```js
|
|
471
|
+
const recording = await mbApi.lookupRecording('16afa384-174e-435e-bfa3-5591accda31c');
|
|
472
|
+
|
|
473
|
+
const succeed = await mbApi.login();
|
|
474
|
+
assert.isTrue(succeed, 'Login successful');
|
|
475
|
+
await mbApi.addSpotifyIdToRecording(recording, '2AMysGXOe0zzZJMtH3Nizb');
|
|
476
|
+
```
|
|
477
|
+
|
|
478
|
+
## Compatibility
|
|
479
|
+
|
|
480
|
+
The JavaScript in runtime is compliant with [ECMAScript 2017 (ES8)](https://en.wikipedia.org/wiki/ECMAScript#8th_Edition_-_ECMAScript_2017).
|
|
481
|
+
Requires [Node.js®](https://nodejs.org/) version 6 or higher.
|