You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: CHANGELOG.md
+9
Original file line number
Diff line number
Diff line change
@@ -1,5 +1,14 @@
1
1
# CHANGELOG
2
2
3
+
## 1.0.0-rc1 (12/25/15) :christmas_tree:
4
+
5
+
* Server/client relationship allows you to run Alda servers in the background and interact with them via a much more lightweight CLI, implemented in Java. Everything is packaged into a single uberjar containing both the server and the client. The client is able to manage/start/stop servers as well as interact with them by handing them Alda code to play, etc.
6
+
* This solves start-up time issues, making your Alda CLI experience much more lightweight and responsive. It still takes a while to start up an Alda server, but now you only have to do it once, and then you can leave the server running in the background, where it will be ready to parse/play code whenever you want, at a moment's notice.
7
+
* Re-implementing the Alda REPL on the client side is a TODO item. In the meantime, you can still access the existing Alda REPL by typing `alda repl`. This is just as slow to start as it was before, as it still has to start the Clojure run-time, load the MIDI system and initialize a score when you start the REPL. In the near future, however, the Alda REPL will be much more lightweight, as it will be re-implemented in Java, and instead of starting an Alda server every time you use it, you'll be interacting with Alda servers you already have running.
8
+
* Starting with this release, we'll be releasing Unix and Windows executables on GitHub. These are standalone programs; all you need to run them is Java. [Boot](http://boot-clj.com) is no longer a dependency to run Alda, just something we use to build it and create releases. For development builds, running `boot build` will generate `alda.jar`, `alda`, and `alda.exe` files which can be run directly.
9
+
* In light of the above, the `bin/alda` Boot script that we were previously using as an entrypoint to the application is no longer needed, and has been removed.
10
+
* Now that we are packaging everything together and not using Boot as a dependency, it is no longer feasible to include a MIDI soundfont with Alda. It is easy to install the FluidR3 soundfont into your Java Virtual Machine, and this is what we recommend doing. We've made this even easier (for Mac & Linux users, at least) by including a script (`scripts/install-fluid-r3`). Running it will download FluidR3 and replace `~/.gervill/soundbank-emg.sf2` (your JVM's default soundfont) with it. (If you're a Windows user and you know how to install a MIDI soundfont on a Windows system, please let us know!)
11
+
3
12
## 0.14.2 (11/13/15)
4
13
5
14
* Minor aesthetic fixes to the way errors are reported in the Alda REPL and when using the `alda parse` task.
Copy file name to clipboardExpand all lines: README.md
+49-18
Original file line number
Diff line number
Diff line change
@@ -1,8 +1,8 @@
1
1
```
2
-
________________________________
2
+
________________________________
3
3
/ o oooo ooo oooo o o o /\
4
4
/ oo ooo oo oooo o o o / /
5
-
/ _________________________ / /
5
+
/ _________________________ / /
6
6
/ // / // /// // /// // /// / / / /
7
7
/___ //////////////////////////_/ /
8
8
\____\________________________\_\/
@@ -73,7 +73,6 @@ of music: classical, popular, chiptune, electroacoustic, and more!
73
73
*[Export to MusicXML](https://github.com/alda-lang/alda/issues/44) for inter-operability with other music software
74
74
*[A more robust REPL](https://github.com/alda-lang/alda/issues/54), tailor-made for editing scores interactively
75
75
*[A plugin system](https://github.com/alda-lang/alda/issues/37) allowing users to define custom/unofficial syntax in Alda scores
76
-
*[An "alda daemon"](https://github.com/alda-lang/alda/issues/49) with server/client semantics
77
76
78
77
If you're a developer and you'd like to help, come on in -- [the water's fine](#contributing)!
79
78
@@ -86,32 +85,64 @@ If you're a developer and you'd like to help, come on in -- [the water's fine](#
86
85
87
86
For more examples, see these [example scores](https://github.com/alda-lang/alda/tree/master/examples).
88
87
89
-
## Quick Start
88
+
## Installation
90
89
91
-
### Installation
92
-
93
-
> NOTE: Default JVM soundfonts usually are of low quality. We recommend installing a nice soundfont like FluidR3 to make your MIDI instruments sound a lot nicer. For your convenience, there is a script in this repo that will install the FluidR3 soundfont.
90
+
> You must have [Java](https://www.java.com/en/download) installed on your system in order to run Alda.
94
91
>
95
-
> More information on this can be found in [the docs](doc/installation.md).
92
+
> (Chances are, you already have Java installed.)
93
+
94
+
### Mac OS X / Linux
95
+
96
+
* Go to the [latest release](https://github.com/alda-lang/alda/releases/latest) page and download `alda`.
97
+
98
+
* Make the file executable:
99
+
100
+
chmod +x alda
101
+
102
+
* Make `alda` available on your `$PATH`:
103
+
104
+
> Using `/usr/local/bin` here as an example;
105
+
> you can use any directory on your `$PATH`.
106
+
107
+
mv alda /usr/local/bin
108
+
109
+
### Windows
110
+
111
+
* Go to the [latest release](https://github.com/alda-lang/alda/releases/latest) page and download `alda.exe`.
112
+
113
+
* Make the `alda` command available by moving `alda.exe` to your system root path:
114
+
115
+
C:\> move alda.exe %SystemRoot%
116
+
117
+
### MIDI soundfonts
118
+
119
+
Default JVM soundfonts usually are of low quality. We recommend installing a good freeware soundfont like FluidR3 to make your MIDI instruments sound a lot nicer. For your convenience, there is a script in this repo that will install the FluidR3 soundfont for Mac and Linux users.
120
+
121
+
> If you're a Windows user and you know how to install a MIDI soundfont to the Java Virtual Machine, please let us know!
122
+
123
+
To install FluidR3 on your Mac or Linux system, clone this repo and run:
124
+
125
+
scripts/install-fluidr3
96
126
97
-
#### Mac OS X / Linux
127
+
This will download FluidR3 and replace `~/.gervill/soundbank-emg.sf2` (your JVM's default soundfont) with it.
98
128
99
-
1. Install [Boot](http://www.boot-clj.com).
100
-
2. Run this command to place the `alda` script in your `$PATH`:
For the best experience when editing Alda score files, install the [Alda file-type plugin](doc/installation.md/#editor-plugins) for your editor of choice.
141
+
We're still working on [improving the Alda update process](https://github.com/alda-lang/alda/issues/82). Ideally you'll be able to just type `alda update` to get the latest version.
111
142
112
-
### Demo
143
+
For now, you can update Alda by downloading the [latest release](https://github.com/alda-lang/alda/releases/latest) and repeating the install process.
113
144
114
-
> NOTE: The first time you run one of these tasks, you may need to wait a minute for the FluidR3 MIDI soundfont dependency (~141 MB) to download. Alda uses this soundfont in order to make your JVM's MIDI instruments sound a lot nicer. If you'd prefer to skip this step and use your JVM's default soundfont instead, include the `--stock` flag (i.e. `play --stock --file ...`).
Go is a quirky language. It looks like there are roughly 4.2 billion ways to organize and build Go projects, many of which rely on fumbling with the `$GOPATH` environment variable. `gb` seems to be the most sensible way to do project-based builds.
8
-
9
-
To build the latest version of the `alda` client for development purposes:
10
-
11
-
1. Install [`gb`](https://getgb.io/).
5
+
## Usage
12
6
13
-
2. Fetch dependencies by running `gb vendor restore`.
7
+
For information about available tasks, run `alda help`.
14
8
15
-
3. Build the project by running `gb build alda`. This builds an executable for your platform, located at `bin/alda`.
9
+
## Development
16
10
17
-
## Usage
11
+
See the [development guide](../doc/development-guide.md).
18
12
19
-
For information about available tasks, run `alda help`.
Copy file name to clipboardExpand all lines: doc/alda-now.md
+5-5
Original file line number
Diff line number
Diff line change
@@ -2,7 +2,7 @@
2
2
3
3
`alda.now`, when coupled with [`alda.lisp`](alda-lisp.md), provides a way to work with Alda scores and play music programmatically within a Clojure application.
4
4
5
-
`alda.now` provides a `play!` macro, which evaluates the body, finds any new note events that were added to the score, and plays them.
5
+
`alda.now` provides a `play!` macro, which evaluates the body, finds any new note events that were added to the score, and plays them.
6
6
7
7
Example usage of `alda.now` in a Clojure application:
8
8
@@ -14,7 +14,7 @@ Example usage of `alda.now` in a Clojure application:
14
14
(part*"upright-bass")
15
15
16
16
; This is optional. If left out, Alda will set up the MIDI synth the first
17
-
; time you tell it to play something.
17
+
; time you tell it to play something.
18
18
(set-up!:midi)
19
19
20
20
(play!
@@ -26,9 +26,9 @@ Example usage of `alda.now` in a Clojure application:
26
26
(note (pitch:g) (duration (note-length4))))
27
27
```
28
28
29
-
Of note, [`alda.repl`](alda-repl.md) uses `alda.now` to play the score the user is creating during the REPL session, so you could think of `alda.repl` as an `alda.now`"sample project."
29
+
Of note, [`alda.repl`](alda-repl.md) uses `alda.now` to play the score the user is creating during the REPL session, so you could think of `alda.repl` as an `alda.now` sample project.
30
30
31
-
Another thing to note is that `alda.now` does not load the FluidR3 MIDI soundfont like the CLI version of Alda does by default. In the near future, Alda may be packaged with FluidR3 and `alda.now` could provide a simple helper method to load FluidR3. Currently, FluidR3 is loaded dynamically by the Alda CLI.
31
+
## MIDI soundfonts
32
32
33
-
If you are interested in using FluidR3 or other MIDI soundfonts with Alda in a Clojure application, you can use [`midi.soundfont`](https://github.com/daveyarwood/midi.soundfont).
33
+
The default JVM soundfont sounds pretty bad. If you're using Alda in a Clojure application and you want to have nice MIDI sounds, you can use [`midi.soundfont`](https://github.com/daveyarwood/midi.soundfont) to load FluidR3 or another MIDI soundfont into the JVM at runtime.
Copy file name to clipboardExpand all lines: doc/development-guide.md
+43-32
Original file line number
Diff line number
Diff line change
@@ -1,14 +1,45 @@
1
1
# Development Guide
2
2
3
+
## Building the Project
4
+
5
+
The Alda client and server are packaged together in the same uberjar. You can build the project by running a single command (requires [Boot](http://boot-clj.com)), `boot build`, while in the root directory of this repo. Note that this command requires an `-o/--output-dir` argument, which is the directory where the executable files `alda` and `alda.exe` will be written. I like to use `/tmp` (`boot build -o /tmp`). I can then try out changes by running `/tmp/alda <cli args here>`.
6
+
7
+
Note that the client forks server processes into the background, which continue to run even after the client has exited. If you're testing out changes you've made to the server code, you will need to restart the server by running `alda restart`, which will stop the server and start a new process using your new build.
8
+
9
+
## Testing changes
10
+
11
+
### Running tests
12
+
13
+
You should run `boot test` prior to submitting any Pull Request involving changes to the server. This will run automated tests that live in the `server/test` directory.
14
+
15
+
#### Adding tests
16
+
17
+
It is generally good to add to the existing tests wherever it makes sense, i.e. whenever there is a new test case that Alda needs to consider. [Test-driven development](https://en.wikipedia.org/wiki/Test-driven_development) is a good idea.
18
+
19
+
If you find yourself adding a new file to the tests, be sure to add its namespace to the `test` task option in `build.boot` so that it will be included when you run the tests via `boot test`.
20
+
21
+
## Client
22
+
23
+
The Alda client is a fairly straightforward Java CLI app that uses [JCommander](http://jcommander.org) to parse command-line arguments.
24
+
25
+
Interaction with servers is done via simple HTTP requests. Unless specified via the `-H/--host` option, the Alda client assumes the servers are run locally and sends requests to localhost. The default port is 27713.
26
+
27
+
Running `alda start` forks a new Alda process in the background, passing it the (hidden) `server` command to start the server. Server output is hidden from the user (though the client will report errors). To see server output for development purposes, you can start a server in the foreground by running `alda server`. You may specify a port via the `-p/--port` option (e.g. `alda -p 2000 server`) -- just make sure you're sending requests from the client to the right port (e.g. `alda -p 2000 play -f my-score.alda`).
28
+
29
+
To stop a server, run `alda stop`. To restart a server (e.g. to try out changes to the server code), run `alda restart` after re-building the project.
30
+
31
+
## Server
32
+
33
+
The Alda server is written in Clojure. It handles a variety of things, including parsing Alda code into executable Clojure code, executing the code to create or modify a score, modeling a musical score as a Clojure map of data, and using the map of data as input to interpret the score (generating sound).
34
+
3
35
*[alda.parser](#aldaparser)
4
36
*[alda.lisp](#aldalisp)
5
37
*[alda.sound](#aldasound)
6
38
*[alda.now](alda-now.md)
7
39
*[alda.repl](#aldarepl)
40
+
*[alda.server](#aldaserver)
8
41
9
-
Alda is a program that takes a string of code written in Alda syntax, parses it into executable Clojure code that will create a score, and then plays the score.
10
-
11
-
## alda.parser
42
+
### alda.parser
12
43
13
44
Parsing begins with the `parse-input` function in the [`alda.parser`](https://github.com/alda-lang/alda/blob/master/server/src/alda/parser.clj) namespace. This function uses a series of parsers built using [Instaparse](https://github.com/Engelberg/instaparse), an excellent parser-generator library for Clojure.
14
45
The grammars for each step of the parsing process are composed from [small files written in BNF](https://github.com/alda-lang/alda/blob/master/server/grammar) (with some Instaparse-specific sugar); if you find yourself editing any of these files, it may be helpful to read up on Instaparse. [The tutorial in the Instaparse README](https://github.com/Engelberg/instaparse) is comprehensive and excellent.
@@ -63,7 +94,7 @@ alda.parser=> (parse-input "piano: c8 e g c1/f/a")
63
94
(alda.lisp/pitch:a)))))
64
95
```
65
96
66
-
## alda.lisp
97
+
###alda.lisp
67
98
68
99
When you evaluate a score [S-expression](https://en.wikipedia.org/wiki/S-expression) like the one above, the result is a map of score information, which provides all of the data that Alda's audio component needs to make an audible version of your score.
69
100
@@ -131,9 +162,9 @@ When you evaluate a score [S-expression](https://en.wikipedia.org/wiki/S-express
131
162
132
163
There are 3 keys in this map:
133
164
134
-
***events** -- a set of note events
135
-
***markers** -- a map of marker names to offsets, expressed as milliseconds from the beginning of the score (`:start` is a special marker that is always placed at offset 0)
136
-
***instruments** -- a map of randomly-generated ids to all of the information that Alda has about an instrument, *at the point where the score ends*.
165
+
***:events** -- a set of note events
166
+
***:markers** -- a map of marker names to offsets, expressed as milliseconds from the beginning of the score (`:start` is a special marker that is always placed at offset 0)
167
+
***:instruments** -- a map of randomly-generated ids to all of the information that Alda has about an instrument, *at the point where the score ends*.
137
168
138
169
A note event contains information such as the pitch, MIDI note and duration of a note, which instrument instance is playing the note, and what its offset is relative to the beginning of the score (i.e., where the note is in the score)
139
170
@@ -156,15 +187,15 @@ Because `alda.lisp` is a Clojure DSL, it's possible to use it to build scores wi
156
187
(note (pitch:c))))
157
188
```
158
189
159
-
## alda.sound
190
+
###alda.sound
160
191
161
192
The `alda.sound` namespace handles the implementation details of playing the score.
162
193
163
194
There is an "audio type" abstraction which refers to different ways to generate audio, e.g. MIDI, waveform synthesis, samples, etc. Adding a new audio type is as simple as providing an implementation for each of the multimethods in this namespace, i.e. `set-up-audio-type!`, `refresh-audio-type!`, `tear-down-audio-type!` and `play-event!`.
164
195
165
196
The `play!` function handles playing an entire Alda score. It does this by using [overtone.at-at](https://github.com/overtone/at-at) to schedule all of the note events to be played via `play-event!`, based on the `:offset` of each event.
166
197
167
-
### alda.lisp.instruments
198
+
####alda.lisp.instruments
168
199
169
200
Although technically a part of `alda.lisp`, stock instrument configurations are defined here, which are included in an Alda score map, and then used by `alda.sound` to provide details about how to play an instrument's note events. Each instrument's `:config` field is available to the `alda.sound/play-event!` function via the `:instrument` field of the event.
170
201
@@ -176,29 +207,9 @@ There are built-in commands defined in `alda.repl.commands` that are defined usi
176
207
177
208
The core logic for what goes on behind the curtain when you use the REPL lives in `alda.repl.core`. A good practice for implementing a REPL command in `alda.repl.commands` is to move implementation details into `alda.repl.core` (or perhaps into a new sub-namespace of `alda.repl`, if appropriate) if the body of the command definition starts to get too long.
178
209
179
-
## Testing changes
180
-
181
-
There are a couple of [Boot](http://boot-clj.com) tasks provided to help test changes.
182
-
183
-
### `boot test`
184
-
185
-
You should run `boot test` prior to submitting a Pull Request. This will run automated tests that live in the `test` directory.
186
-
187
-
#### Adding tests
188
-
189
-
It is a good idea in general to add to the existing tests wherever it makes sense, i.e. if there is a new test case that Alda needs to consider. [Test-driven development](https://en.wikipedia.org/wiki/Test-driven_development) is a good idea.
190
-
191
-
If you find yourself adding a new file to the tests, be sure to add its namespace to the `test` task option in `build.boot` so that it will be included when you run the tests via `boot test`.
192
-
193
-
### `boot alda`
194
-
195
-
When you run the `alda` executable, it uses the most recent *released* version of Alda. So, if you make any changes locally, they will not be included when you run `alda repl`, `alda play`, etc.
196
-
197
-
For testing local changes, you can use the `boot alda` task, which uses the current state of the repository, including any local changes you have made.
198
-
199
-
#### Example usage
210
+
### alda.server
200
211
201
-
boot alda -x repl
212
+
`alda.server/start-server!` is the entrypoint to the Alda server. It starts a Clojure web app using [Ring](https://github.com/ring-clojure/ring) and [Compojure](https://github.com/weavejester/compojure), and serves it via [Jetty](https://en.wikipedia.org/wiki/Jetty_(web_server)).
202
213
203
-
boot alda -x "play --code 'piano: c d e f g'"
214
+
Requests can be made to the server via any HTTP client, e.g. curl, or via the Alda client, which communicates with the server by making HTTP requests.
0 commit comments