1---
2title: Music metadata
3layout: ../../layouts/MainLayout.astro
4---
5
6import { MiniRepl } from '../../docs/MiniRepl';
7import { JsDoc } from '../../docs/JsDoc';
8
9# Music metadata
10
11You can optionally add some music metadata in your Strudel code, by using tags in code comments:
12
13```js
14// @title My Cool Song
15// @by John Doe
16// @license CC-BY-SA-4.0
17```
18
19Like other comments, those are ignored by Strudel, but it can be used by other tools to retrieve some information about the music.
20
21## Alternative syntax
22
23You can also use comment blocks:
24
25```js
26/*
27@title My Cool Song
28@by John Doe
29@license CC-BY-SA-4.0
30*/
31```
32
33Or define multiple tags in one line:
34
35```js
36// @title My Cool Song @by John Doe @license CC-BY-SA-4.0
37```
38
39The `title` tag has an alternative syntax using quotes (must be defined at the very begining):
40
41```js
42// "My Cool Song" @by John Doe
43```
44
45## Tags list
46
47Available tags are:
48
49- `@title`: music title
50- `@by`: music author(s), separated by comma, eventually followed with a link in `<>` (ex: `@by John Doe <https://example.com>`)
51- `@license`: music license(s), separated by comma. Each license should be specified by using the correct identifier in the [https://spdx.org/licenses/](SPDX License List). Example: CC-BY-SA-4.0. Unsure? [Choose a Creative Commons license here](https://creativecommons.org/choose/).
52- `@details`: some additional information about the music
53- `@url`: web page(s) related to the music (git repository, Soundcloud link, etc.)
54- `@genre`: music genre(s) (pop, jazz, etc.)
55- `@album`: music album name
56- `@tag`: custom tag
57
58Note to tool authors: _Never_ trust that a song has filled those fields with syntactically correct values; make sure your software is robust enough it doesn't break if it encounters bad values
59
60## Multiple values
61
62Some of them accepts several values, using the comma or new line separator, or duplicating the tag:
63
64```js
65/*
66@by John Doe
67    Jane Doe
68@genre pop, jazz
69@url https://example.com
70@url https://example.org
71*/
72```
73
74You can also add optional prefixes and use tags where you want:
75
76```js
77/*
78song @by John Doe
79samples @by Jane Doe
80*/
81...
82note("a3 c#4 e4 a4") // @by Sandy Sue
83```
84
85## Multiline
86
87If a tag doesn't accept a list, it can take multi-line values:
88
89```js
90/*
91@details I wrote this song in February 19th, 2023.
92         It was around midnight and I was lying on
93         the sofa in the living room.
94*/
95```
96
97# Searching meta-data in the online repl
98
99Meta-data can be used in the search field of the patterns tab in the online repl.
100
101For example to search for all patterns by a specific author use the search term
102
103```
104by: Ada L
105```
106
107or search for patterns with a specific genre like
108
109```
110genre: unicorns
111```
112
113Hint: If no meta-data property is provided in the search all patterns with a `@title`, `@by` or `@tag` matching the search term will be shown.