{"id":20671304,"url":"https://github.com/allnulled/nalda","last_synced_at":"2025-08-23T10:07:10.013Z","repository":{"id":98546880,"uuid":"300424898","full_name":"allnulled/nalda","owner":"allnulled","description":"Nalda is a programming language, based on Alda, but uses Numbers to refer to each musical note.","archived":false,"fork":false,"pushed_at":"2020-10-03T21:15:28.000Z","size":66,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-01-17T13:48:17.267Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/allnulled.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-10-01T21:05:48.000Z","updated_at":"2020-10-03T21:15:31.000Z","dependencies_parsed_at":"2023-05-29T11:40:46.225Z","dependency_job_id":null,"html_url":"https://github.com/allnulled/nalda","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/allnulled%2Fnalda","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/allnulled%2Fnalda/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/allnulled%2Fnalda/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/allnulled%2Fnalda/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/allnulled","download_url":"https://codeload.github.com/allnulled/nalda/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":242890531,"owners_count":20202166,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-16T20:26:17.152Z","updated_at":"2025-03-10T17:25:14.456Z","avatar_url":"https://github.com/allnulled.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# nalda\n\nProgramming language to create music by numbers and javascript templates.\n\n`nalda` is a programming language, based on [`alda`](https://alda.io/), but uses numbers to refer to each musical note.\n\nWith `nalda`, you can write music as if it was a program, using numbers, and even javascript as templating language.\n\n`nalda` is because of: **N**umbers + **Alda**.\n\n\n## Prerequisites\n\n### 1. Download and install `alda` tool\n\n- [Here](https://github.com/alda-lang/alda/blob/master/README.md) you can find how to install and run Alda documents.\n\n- [Here](https://blog.djy.io/alda-a-manifesto-and-gentle-introduction/) you can find an Alda tutorial, but you should not need it, as `nalda` should do the work.\n\n### 2. Download and install `npm` and `node`\n\nOnce here, we can run `alda` scripts. But we need `npm` and `node` to be able to download and install `nalda` yet.\n\n- [Here](https://nodejs.org/en/download/) you can install both `npm` and `node` at once.\n\n### 3. Download and install `nalda`\n\nOnce here, we can install and manage packets for `node` and `npm`. But we still do not have `nalda` installed.\n\nNow, go to [`nalda` github project](https://github.com/allnulled/nalda) and download the project.\n\nOpen the folder, and with the command-line console, install the dependencies runnning from the inside of the project folder:\n\n```batch\nnpm install\n```\n\nThis will install the `nalda` dependencies, and from there, you can start.\n\n### 4. OK\n\nIf you arrived here, you are almost ready to go with `nalda`.\n\nYou do NOT have to repeat the previous steps anymore.\n\n\n## Get started\n\nDespite we installed all the tools we need to play with `nalda`, you still have to do 2 things before writting and listening your `nalda` scripts.\n\n### 1. Set up alda server\n\nThe first thing you have to do to play with `nalda` is to turn `alda` server up like this:\n\n```batch\nalda up\n```\n\nThis has to be done only once, this is a background process we need to have working for us to listen `alda` scripts. This step takes some time.\n\n### 2. Set up nalda watchers\n\nNow, we want `nalda` to start listening our programs. We can do this typing on the console:\n\n```batch\nnode watcher\n```\n\nThis command will make `nalda` to watch our files in order to, automatically, play them once it has detected that you saved a `nalda` file.\n\nFinally, done. Now, we have the folder `composer/`, where anytime we save a file with the extension `*.nalda`, the `nalda` tool will compile the script automatically and play it.\n\n#### About the nalda script compilation\n\nThe compilation of `nalda` scripts produce different files:\n\n  - `*.nalda`: this is our script, the one we write.\n  - `*.calda`: this is our script, without comments.\n    - This is for you to use `/* .... */` style comments in your `alda` code.\n  - `*.talda`: this is our script, without comments, and as already rendered template.\n    - For programmers who know about javascript\n    - This is for you to use [ejs templates](https://github.com/mde/ejs) in your scripts.\n    - This allows you to play with javascript directly to create music.\n    - Note that delimiters are set to `\u003c/` and `/\u003e` for the ejs, instead of the common `\u003c%` and `%\u003e`.\n\n\n## The language of nalda\n\n`nalda` is a program, but also a programming language that can be interpreted by this program.\n\nNow, we are going to talk about the language, and not the program.\n\nEach script can play with different concepts, put them together and mix them as you prefer.\n\nThe following are all the concepts that you can play with in `nalda`.\n\n### 1. Instruments\n\nFirst of all, in your `nalda` script you have to specify an instrument.\n\n```nalda\npiano:  0\nguitar: 0\n```\n\nThis script, for example, is going to play a `do` note in both, piano and guitar. The `0` is a `do` here.\n\nYou can play and repeat as much instruments as you want.\n\n### 2. Voices\n\nAfter the instrument, you can specify various voices per each instrument, who will play simultaneously. For example:\n\n```nalda\npiano: \n  voice 1: 0\n  voice 2: scaleup 0\n  voice 3: scaleup 0\n```\n\nHere, we are playing 3 `do`s (of different scales, but that is explained later) with different pianos simultaneously.\n\nNotice that this would be a way to create chords, but that is also explained later, and this is not the only, nor the best way to do it.\n\n\n### 3. Octave\n\nYou can change the octave of the following notes by `octave` directive, like this:\n\n```nalda\npiano: octave:1 0\npiano: octave:2 0\npiano: octave:3 0\npiano: octave:4 0\npiano: octave:5 0\npiano: octave:6 0\npiano: octave:7 0\n```\n\nYou can hear the different sounds of `0` depending on the octave they are being played over.\n\n**Once you specify this directive, the following notes will be affected by it.**\n\n### 4. Tempo\n\nWith `nalda` we can play with the tempo of the played notes too.\n\nThere are 2 ways of tempo specification: global, which affects to all the voices and instruments, or local, which affects only to the voice they are specified from.\n\nThe tempo directive affects a whole instrument, when local, and the whole following notes, when global.\n\n**Once you specify this directive, the following notes will be affected by it.**\n\nThe following examples are the same script, but applying local tempo in the first, and global tempo in the second. You can hear the differences.\n\n### 4.1. Local tempo\n\nWhen you play this example:\n\n```nalda\nguitar:\n  scaledown\n  0 0 0 0\n  tempo: 200\n  0 0 0 0\n  tempo: 400\n  0 0 0 0\n  tempo: 800\n  0 0 0 0\npiano:\n  scaleup\n  0 0 0 0\n  0 0 0 0\n  0 0 0 0\n  0 0 0 0\n```\n\nAs you can hear, this script makes the guitar play faster when tempo is increased, but not the piano. This is because we used a `local tempo` directive.\n\n### 4.2. Global tempo\n\nWhen you play this example:\n\n```nalda\nguitar:\n  scaledown\n  0 0 0 0\n  tempo: 200!\n  0 0 0 0\n  tempo: 400!\n  0 0 0 0\n  tempo: 800!\n  0 0 0 0\npiano:\n  scaleup\n  0 0 0 0\n  0 0 0 0\n  0 0 0 0\n  0 0 0 0\n```\n\nAs you can hear, this script makes the guitar play faster when tempo is increased, and the piano too gets played faster. This is because we used a `global tempo` directive.\n\n### 5. Scale\n\nIn order to abbreviate the calculus, basically, we can jump up and down scales. This means:\n\n```nalda\npiano:\n  scaledown 0 2\n  scaledown 0 2\n  scaleup 0 2\n  scaleup 0 2\n```\n\nThis way, we play the same notes, but 12 semitones up, or down, but using the same numbers.\n\n**Once you specify this directive, the following notes will be affected by it.**\n\n### 6. Moment\n\nMoments are just points on time that you label, so you can start writting music played at that moment in other parts of your script.\n\nFor this purpose, we have 2 directives:\n\n  - Moment definition: directive that specifies a point to which we can insert music from other points.\n    - `@moment-name!`\n    - Ends with `!`\n  - Moment usage: directive that specifies what to insert in a moment definition previously used.\n    - `@moment-name:`\n    - Ends with `:`\n\nThis example demonstrates how moments work in `nalda`:\n\n```nalda\npiano: 0 2 4 @introductionMoment! 6 8 10 12 14 16 18\nguitar: @introductionMoment: 6 8 10 12 14 16 18\n```\n\n### 7. Note\n\nThe notes are the basic element of the language.\n\nNotes are represented by numbers that represent semitone jumps.\n\nSo what we have is this equivalence between `nalda` and `alda` notes:\n\n  - `0` is an `a`\n  - `2` is an `b`\n  - `3` is an `c`\n  - `5` is an `d`\n  - `7` is an `e`\n  - `8` is an `f`\n  - `10` is an `g`\n  - `12` is an `\u003ea`\n\nSo, for example, we can write this 2 voices that sound the same:\n\n```\npiano:\n   voice 1:    0 2 3 5 7 8 10 12\n   voice 2: [[ a b c d e f g  \u003ea ]]\n```\n\nThe `voice 1` is in `nalda` syntax.\n\nThe `voice 2` is in embedded `alda` syntax.\n\n#### 7.1. Note modifiers\n\nNotes accept modifiers:\n\n  - `longitude`:\n    - Represents the duration of a note.\n    - Its syntax is: `4L` `8L` `16L` `32L` \n    - `4L` is the default (represents a black note, while `2L` represents a white note)\n    - This magnitude represents the tempo divider, so, the higher this number is, the faster the note expires.\n  - `timing`:\n    - Represents the duration of a note, but directly into `seconds` or `milliseconds`.\n    - Its syntax is: `2500MS` (2.5 seconds) `4S` (4 seconds) `1S` (1 second) and so on... \n    - There is no default value\n    - This magnitude represents the longitude of a note, but directly into `seconds` or `milliseconds`\n  - `quantification`:\n    - Represents the length of a note without changing its duration\n    - Its syntax is: `0D` `20D` `40D` `60D` `80D` `100D` \n    - `100D` is the default\n    - This magnitude is a percentage\n  - `volume`:\n    - Represents the volume of a note\n    - Its syntax is: `0V` `20V` `40V` `60V` `80V` `100V` \n    - `100V` is the default\n    - This magnitude is a percentage\n\nThe order of the modifiers has to be always the same, so, for example, you cannot add the volume before the longitude.\n\nTo play with this modifiers, you have to add them just after the note.\n\nThis example demonstrates the **volume** of a note:\n\n```nalda\npiano:\n\t0  20V\n\t2  30V\n\t4  40V\n\t6  50V\n\t8  60V\n\t10 70V\n\t12 80V\n\t14 90V\n\t16 100V\n```\n\nThis example demonstrates the **quantification** of a note:\n\n```nalda\npiano:\n\t0  10Q\n\t12 1000Q\n```\n\nThis example demonstrates the **longitude** of a note:\n\n```nalda\npiano:\n\t0  16L\n\t.  4L\n\t0  8L\n\t.  4L\n\t0  4L\n\t.  4L\n\t0  2L\n\t.  4L\n\t0  1L\n```\n\n### 8. Chord\n\n`nalda` accepts chords, which are just multiple notes starting at the same time.\n\nThe same modifiers appliable to notes, can be applied to chords.\n\nWhen a chord receives modifiers, these modifiers affect to all the notes inside, except if the specific notes override that modifier(s), in which case the modifier applied to the note overrides the general chord modifiers.\n\nFor example:\n\n```nalda\npiano:\n  { 0 1L 100V 7 12 } 4L 20V \n  { 3 1L 100V 7 10 } 2L 20V\n  { 0 1L 100V 7 12 } 4L 60V\n  { 0 1L 100V 5 10 } 2L 20V\n```\n\nAs you will notice, the modifiers applied to the chord are maintained to all the notes inside, except for these which also specify their own modifiers.\n\nYou can put as much notes as you want in a chord.\n\n### 9. Silence\n\nThe silence in `nalda` acts as if it was one more note, but without volume.\n\nThis means that you can apply the same note and chord modifiers.\n\nSilences are represented with a `.` and its modifiers go behind, after a space, as in notes and chords.\n\nFor example:\n\n```nalda\npiano:\n  0 . 8L 0 . 8L \n```\n\n### 10. Embedded alda\n\nAs `nalda` is just an interface to generate `alda` code, we can also embed `alda` code directly to our scripts.\n\nThis is done by expressions between `[[` and `]]`.\n\nWe cannot, though, embed `alda` code anywhere.\n\nThe embedded `alda` code acts just like if it was a note or a chord, and we only can insert it in places where a note or a chord could go.\n\nNote that `alda` and `nalda` are 2 separate syntax to write the same thing, but you cannot mix them except because of this feature of `nalda`.\n\nFor example:\n\n```nalda\npiano: [[ a b c ]]\n```\n\nThe idea is to be able to do anything that the underlying `alda` version lets you, without affecting `nalda` syntax.\n\n### 11. Comments\n\n`nalda` allows you to embed comments in its code too, using the `/**` and `**/` multiline comments.\n\nYou can put wherever you want these symbols and whatever you want inside of them, because in the `alda` output script, they will not appear.\n\n### 12. Templating\n\nFinally, a very cool feature of `nalda` is that you can play with JavaScript to use variables, conditionals, functions, loops or whatever.\n\n*How is that?*\n\nThis is because `nalda` scripts are [ejs templates](https://github.com/mde/ejs) before becoming `alda` scripts.\n\nThe only thing to know before getting hands dirty with this feature is that the `ejs` delimiter is set to `\"/\"` in `nalda` scripts, so instead of `\u003c%` and `%\u003e`, we have to use `\u003c/` and `/\u003e`.\n\nThis is a very simple example demonstrating that `ejs` is absolutely valid for you to play with in your `nalda` scripts.\n\n```nalda\n\u003c/ const chord1 = \"5 10 15 20\" /\u003e\npiano: { \u003c/- chord1 /\u003e }\n```\n\n#### 12.1. EJS linter\n\nDue to the problems that could arise, `nalda` comes bundled with a small functionality that can help you to identify syntax errors inside the scriptlets of `ejs`.\n\nTo check if the grammar of javascript inside your scriptlets seems correct, you can run this command from the command-line:\n\n```batch\nnpm run lint\n```\n\n#### 12.2. Nalda JavaScript API\n\nTo accelerate the process of creating music, `nalda` comes with a very small and simple API, for you to manage programmatically, if you want:\n\n   - chords: `nalda.Chord`\n   - note: `nalda.Note`\n\nYou can try this example, which is quite simple but can demonstrate what we are talking about.\n\n```nalda\n\u003c/\nconst chord1 = nalda.Chord.create({ notes: [0,7,12,15,19,24], modifiers: {longitude: 2} }); // mi\nconst chord2 = nalda.Chord.create({ notes: [3,7,10,15,22,27] }); // sol\nconst chord3 = nalda.Chord.create({ notes: [0,5,10,17,22,26] }); // re\nconst chordLength = 8;\nconst silenceLength = 32;\n/\u003e\n\npiano:\nvoice 1:\n  octave:2\n\n  \u003c/-chord1/\u003e \u003c/-chord1/\u003e . \u003c/-silenceLength/\u003eL\n  \u003c/-chord1/\u003e \u003c/-chord1/\u003e . \u003c/-silenceLength/\u003eL\n\n  \u003c/-chord2/\u003e \u003c/-chordLength/\u003eL \u003c/-chord2/\u003e \u003c/-chordLength/\u003eL . \u003c/-silenceLength/\u003eL\n  \u003c/-chord2/\u003e \u003c/-chordLength/\u003eL \u003c/-chord2/\u003e \u003c/-chordLength/\u003eL . \u003c/-silenceLength/\u003eL\n\n  \u003c/-chord3/\u003e \u003c/-chordLength/\u003eL \u003c/-chord3/\u003e \u003c/-chordLength/\u003eL . \u003c/-silenceLength/\u003eL\n  \u003c/-chord3/\u003e \u003c/-chordLength/\u003eL \u003c/-chord3/\u003e \u003c/-chordLength/\u003eL . \u003c/-silenceLength/\u003eL\n\n  \u003c/-chord1/\u003e\n```\n\nBut do not take this API too seriously, its purpose is more about suggesting, than giving true help, it just encapsulates programmatically the basic information of chords and notes, nothing else.\n\nThe API is defined at `dev/nalda-api.js`.\n\n#### Predefined chords\n\nYou may find very useful to use the `nalda.chord` API, which lets you write chords fastly.\n\nAll the chords available right now are:\n\n```nalda\nnalda.chord.do\nnalda.chord.dom\nnalda.chord.do7\nnalda.chord.doSos\nnalda.chord.doSosm\nnalda.chord.doSos7\nnalda.chord.re\nnalda.chord.rem\nnalda.chord.re7\nnalda.chord.reSos\nnalda.chord.reSosm\nnalda.chord.reSos7\nnalda.chord.mi\nnalda.chord.mim\nnalda.chord.mi7\nnalda.chord.miSos\nnalda.chord.miSosm\nnalda.chord.miSos7\nnalda.chord.fa\nnalda.chord.fam\nnalda.chord.fa7\nnalda.chord.faSos\nnalda.chord.faSosm\nnalda.chord.faSos7\nnalda.chord.sol\nnalda.chord.solm\nnalda.chord.sol7\nnalda.chord.solSos\nnalda.chord.solSosm\nnalda.chord.solSos7\nnalda.chord.la\nnalda.chord.lam\nnalda.chord.la7\nnalda.chord.laSos\nnalda.chord.laSosm\nnalda.chord.laSos7\nnalda.chord.si\nnalda.chord.sim\nnalda.chord.si7\n```\n\nAnd their synonims, using the other popular notation:\n\n```nalda\nnalda.chord.C\nnalda.chord.Cm\nnalda.chord.C7\nnalda.chord.CSos\nnalda.chord.CSosm\nnalda.chord.CSos7\nnalda.chord.D\nnalda.chord.Dm\nnalda.chord.D7\nnalda.chord.DSos\nnalda.chord.DSosm\nnalda.chord.DSos7\nnalda.chord.E\nnalda.chord.Em\nnalda.chord.E7\nnalda.chord.ESos\nnalda.chord.ESosm\nnalda.chord.ESos7\nnalda.chord.F\nnalda.chord.Fm\nnalda.chord.F7\nnalda.chord.FSos\nnalda.chord.FSosm\nnalda.chord.FSos7\nnalda.chord.G\nnalda.chord.Gm\nnalda.chord.G7\nnalda.chord.GSos\nnalda.chord.GSosm\nnalda.chord.GSos7\nnalda.chord.A\nnalda.chord.Am\nnalda.chord.A7\nnalda.chord.ASos\nnalda.chord.ASosm\nnalda.chord.ASos7\nnalda.chord.B\nnalda.chord.Bm\nnalda.chord.B7\n```\n\nFor example, a simple song could be written like this:\n\n```nalda\n/*********************************************\n **** Con el diablo al lado - Zona Ganjah ****\n *********************************************/\n\n\u003c/\n\nconst { chord } = nalda;\nconst reggaeRythm = function(chord1, chord2, chord3, chord4) {\n  return `\n  . 0.500s ${ chord1 } 0.001s . 0.100s ${ chord1 } 0.001s\n  . 0.500s ${ chord1 } 0.001s . 0.100s ${ chord1 } 0.001s\n  . 0.500s ${ chord2 } 0.001s . 0.100s ${ chord2 } 0.001s\n  . 0.500s ${ chord2 } 0.001s . 0.100s ${ chord2 } 0.001s\n  . 0.500s ${ chord3 } 0.001s . 0.100s ${ chord3 } 0.001s\n  . 0.500s ${ chord3 } 0.001s . 0.100s ${ chord3 } 0.001s\n  . 0.500s ${ chord4 } 0.001s . 0.100s ${ chord4 } 0.001s\n  . 0.500s ${ chord4 } 0.001s . 0.100s ${ chord4 } 0.001s`;\n};\n/\u003e\n\naccordion:\n voice 1:\n\n  tempo: 1800!\n  \u003c/-reggaeRythm(chord.Fm, chord.Fm, chord.ASosm, chord.Cm)/\u003e\n  \u003c/-reggaeRythm(chord.Fm, chord.Fm, chord.ASosm, chord.Cm)/\u003e\n```\n\nIf you wrap the last template tags in a template loop, you can repeat that chords all the times you want, so you could have a nice base with very few lines.\n\n## Examples of nalda scripts\n\nYou can find the sample scripts found along this document on `composer/examples`.\n\nMove them into `composer/` folder, and save them to hear them, if you turned already on the `alda` server, and the `nalda` watcher.\n\n\n## Issues\n\nAddress your issues to the [issues](#) section of the Github project, if any.\n\n## License\n\n[WTFPL or What The Fuck Public License]. Okay, this is it:\n\n```\n           DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE\n                   Version 2, December 2004\n\nEveryone is permitted to copy and distribute verbatim or modified\ncopies of this license document, and changing it is allowed as long\nas the name is changed.\n \n           DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE\n  TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION\n\n 0. You just DO WHAT THE FUCK YOU WANT TO.\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fallnulled%2Fnalda","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fallnulled%2Fnalda","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fallnulled%2Fnalda/lists"}