-
Notifications
You must be signed in to change notification settings - Fork 26
Home
Welcome to the Estuary wiki!
Official documentation of Estuary is found within Estuary itself. Click on the ? at the top right of the Estuary interface, and then go to Reference. You can find the main 24/7 deployment of Estuary any time at https://estuary.mcmaster.ca.
This Wiki is only for emerging documentation that will eventually migrate to being with the rest of the documentation inside the Estuary interface. Essentially, just partial documentation of emerging features, tips and tricks that don't (or don't yet) belong in the official documentation, etc.
Please feel free to ask questions on the Estuary Discord server (invite link visible in the main Estuary server at https://estuary.mcmaster.ca).
By default, estuary.mcmaster.ca is currently providing the union of the Dirt-samples and estuary-samples repositories as available audio resources. Numerous other sample libraries exist, and can be added "on the fly" to an Estuary ensemble or solo setting, using the terminal. To add the resources from a particular library (a "reslist") to an ensemble, enter !reslist followed by the appropriate URL in quotation marks at the terminal (see also the more detailed instructions in the next section). For example: !reslist "https://dktr0.github.io/cybernetic-samples/sounds/sounds.json"
VCSL library (license: CC0), formatted for Estuary by Carl Testa: https://carltesta.github.io/vcsl_for_estuary/resources.json
Tahti library (license: Boost Software License 1.0), formatted for Estuary by Carl Testa: https://carltesta.github.io/tahti_for_estuary/resources.json
From the Cybernetic Orchestra (license: CC0): https://dktr0.github.io/cybernetic-samples/sounds/sounds.json
From UPLorc - the University of Pretoria Laptop Orchestra (license: CC0): https://djmelan3.github.io/UPLOrc-samples/resources.json
From Gamelan Naga Mas (license: CCO): https://tedthetrumpet.github.io/testpage/nmsamples/resources.json
First of all, any media files to be added (whether in Solo or Collaborative mode) must be available through a CORS-compliant web server. The easiest known way to do this is to make a gh-pages site on a GitHub repository, and commit your files there.
To add an individual sound (available through a CORS-compliant web server), do this at the Estuary terminal (replacing nameOfSampleBank with the sample bank you want the sound to be available through, and replacing 0 with the number/position you want that sound to occupy in that bank): !insertsound "https://complete-url-to-sound.wav" nameOfSampleBank 0
To see the "resource operations" that have been added to your Solo window or Collaborative ensemble, do this at the terminal: !showresources
If you do that, in a new ensemble or Solo window, you'll see just one item that says: reslist "samples/resources.json"
A reslist is a JSON file that points to many available sounds, images, videos. The reslist at "samples/resources.json" is a complete list of the default sound samples set up for the Estuary server. Here's a small sample of what a reslist looks like:
[
{ "url":"808/CB.WAV","type":"audio","bank":"808","n":0},
{ "url":"808/CH.WAV","type":"audio","bank":"808","n":1},
{ "url":"808/CL.WAV","type":"audio","bank":"808","n":2}
]
The URLs in the reslist above are relative to wherever the reslist itself is located on the web. For example, the folder "808" in the above reslist should be in the same folder where the reslist file is located (and so, the WAV files in the above example would be in the 808 folder, ie. below the level of the reslist file). If you are editing/making a restlist by hand: Note that the JSON "keys" in the above MUST be in quotation marks, or it will not work.
If you are adding more than a few sounds, you'll probably want to make reslists for them. If you have your own reslist on the web you can add it to your solo window or collaborative ensemble like so: !reslist "https://complete-url-to-my-custom-samplebank.json"
There is a script in the top folder of the Estuary github repository called generateAudioResources.sh. You can run this BASH script at BASH/the terminal to auto-generate a reslist for a whole folder of folders containing audio samples. That might work like this, assuming your sample bank is located in ~/mySampleBank/ and you have cloned or downloaded the Estuary repository to ~/Estuary/:
cd ~/mySampleBank
~/Estuary/generateAudioResources.sh . > resources.json
After that ~/mySampleBank should have a new file called resources.json in it. You can check it out with a text editor to verify it makes sense, then commit it to your gh-pages repository. You should then be able to use the !reslist command (see above) to add that whole collection of sample banks all in one go (the same script is used at estuary.mcmaster.ca to generate the default resources.json).
To completely erase the defaults (ie. in the current window or ensemble), you can do this in a terminal (note that you will have no samples available until you add something back...): !clearresources
To restore the default resource operations, you can do this in a terminal: !defaultresources
Most users do NOT need to build and run their own Estuary server, and can simply use the server that is always available at estuary.mcmaster.ca. As the estuary.mcmaster.ca is maintained by the principal developer of Estuary (David Ogborn) with a very close knowledge of the issues and challenges involved, that server will almost invariably be the most up-to-date with improvements to the underlying software, is being served by a research and high performance computing cluster at McMaster that provides high up-time and availability, and represents a useful and easy to remember "gathering point" for people "using this stuff".
Probably the most obvious example of a scenario where it might indeed be desirable to build, configure and run your own Estuary server, is the case of performance or workshops in venues where the public Internet is not available or unreliable. Another example might be sessions where all of the networked participants are located on the other side of the world from McMaster AND the extra latency in collaborative editing becomes noticeable (note: (1) it doesn't always become noticeable, (2) may have more to do with the nature of the internet connections between there and McMaster than the absolute physical distance, and (3) this latency has no effect on the quality of rendering audiovisual results by the platform).
Here's a rough list of steps to do this - note that this is relatively difficult software to build and the likelihood of encountering problems due to different operating systems and versions is not close to zero:
-Install stack. version 2.9.3 is known to work (but your mileage may vary). You can verify that is installed with this at a terminal: stack --version
-Clone the dev branch of the estuary repository (or if you already have it, from within that folder pull updates from git). For example: git clone https://github.com/dktr0/Estuary
-Check you have "make" installed and install it somehow if you don't. version 3.8.2 is known to work (probably any version is fine for this one): make --version
-Change into the folder you cloned from git, for example: cd Estuary
-Tell stack to build the server (this could take a while the first time): make stackBuildServer
-Make a standard collection of samples. Here's how to get the Dirt-Samples library: make downloadDirtSamples
-Generate an Estuary resources file for the sample collection: make generateDefaultAudioResources
-Verify that openssl is installed, install it if not: openssl version
-Use openssl to generate self-signed certificates (note that users will get a security warning when connecting to the server that is using self-signed certificates): make selfCertificates
-Stage the estuary server: make stackStageServer
-Download a pre-built Estuary client using the curlReleaseClient.sh script and the numeric identifier of the most recent Estuary release from here https://github.com/dktr0/estuary/releases - currently (12 Sept 2024) that number is 20240516 and so that would look like this: ./curlReleaseClient.sh 20240516
-Run the Estuary server by changing into staging and running it, the first argument after the name of the Estuary server executable will be the moderator password and the second argument will be the community password: cd staging && sudo ./EstuaryServer moderator community +RTS -N -RTS
-You can test your local server by connecting to it from the same machine in your browser: https://127.0.0.1
-Other machines will have to use your actual address on the local network, not 127.0.0.1 (which would refer to themselves)
-Note that this procedure does NOT account for exolangs (e.g. LocoMotion, soon Punctual, etc) that published at Internet locations. To use them in an offline/private network, one would have to download their .js code separately and stage it as part of the server (that's not in these instructions yet...)