Automatically sets up a Jamulus server and a Ardour mixing console on AWS using CDK. Jamulus allows bands to do jam sessions in a remote environment. Ardour is a digital audio workstation which supports thousands of plugins to let your mix sound nice.
- Architecture
- Getting Started - Prerequisites
- Getting Started - Deploy your Jamulus environment
- Settings for your Digital Workstation environment
- Cost savings
- Roadmap
The basic architecture is shown in the image below. We setup a Jamulus Band Server in the AWS cloud which will be available through a defined IP address. In addition, it will set up another EC2 instance prepared for being a mixing console. A third EC2 instance will run the Jamulus Mixing Server which is used to present the mixing result to an audience. A forth server (Windows) runs a Jamulus client which connects to the Jamulus Mixing Server instance, and a Zoom client which connects to the Zoom meeting which the audience is listening to.
Every musician opens one Jamulus instance per instrument or microphone and associates the signal to one instance. The Jamulus instances connect to the Jamulus server. The mixing console opens one Jamulus instance per instrument or microphone and directs the signal to separate input channels on Ardour.
Ardour mixes the different instrument to create a nice and pleasant sound. The master will then be routed to the Jamulus Mixing Server. A presenter will feed this signal into a video conferencing tool like Zoom, so that attendees can listen to the music.
Now, clone the git repository to your local machine (my-aws-jamulus-folder
to
be the local folder where this repository will be copied into). These commands
require nodeJs to be installed:
git clone https://github.com/cabcookie/aws-jamulus.git my-aws-jamulus-folder
cd my-aws-jamulus-folder
# install all dependencies
npm install
If you haven't done already, setup an AWS account, protect it according to the Security Best Practices and create an Access Key for your CLI.
Let us first install the AWS command line tools and the Cloud Development Kit:
# this installs the packages global
sudo npm install -g aws-sdk
sudo npm install -g aws-cdk
In order to connect your machine with your AWS environment, run aws configure
in the command line and follow the instructions in the documentation. This will setup the
account and the region you will use in this environment.
You should be able to access your AWS Account and run commands via the CLI. The following command should show you all users you have created during the setup process:
aws iam list-users
If this command runs into issues, please review all steps in this section again.
As a last step, we need to create a PEM file to be able to securly access our EC2 instances via a secure shell (SSH) or a remote desktop connection (RDP). Create and download your key pair with the following command:
aws ec2 create-key-pair --key-name my-key-pair --query "KeyMaterial" --output text > my-key-pair.pem
This will create a key pair in the region you defined before. Your will find your key pair in your AWS EC2 Console in the section Key Pairs:
When replacing [region]
with the region you configured before
(e.g., eu-west-1), you will find your key pairs here:
https://[region].console.aws.amazon.com/ec2/v2/home?region=[region]#KeyPairs:
As a last preparation step you need to create your config.json, according to the
example in ./bin/example-config.json
. So, copy the file to a file named
./bin/config.json
and adjust the settings to your needs. Find more information
on these setting in the section Settings for your Jamulus environment.
Now, that you have cloned the repository, installed all tools and dependencies, set up your AWS environment, and have your key pair ready, you can deploy your Jamulus environment.
As you do this the first time, you need to bootstrap your assets:
cdk bootstrap
You do not need to run this command later again. Now, to deploy your environment, you just run:
cdk deploy
This will take a couple of minutes and it will let you know when its finished by giving you the IP addresses for the 4 servers created by the CDK:
✅ DigitalWorkstation
Outputs:
DigitalWorkstation.JamulusBandServerPublicIp = 1.2.3.4
DigitalWorkstation.JamulusMixingServerPublicIp = 1.2.3.5
DigitalWorkstation.JamulusZoomServerPublicIp = 1.2.3.6
DigitalWorkstation.OnlineMixerMixingConsoleIpABCD = 1.2.3.7
When you have provided Elastic IPs (see below in Settings for your Jamulus environment),
these IP addresses will always be the same. Otherwise, those IP addresses will
change whenever you destroy one of the EC2 instances and create them again. This
happens whenever you destroy the environment or
whenever you change something in the settings or in the startup script and you
run cdk deploy
again to implement the changes.
If you change any code or settings in your
config.json
and you want
to test those before you create the resources in the AWS Cloud, run the
following command:
cdk synth
This will create the CloudFormation template based on your settings and it will tell you if it runs into any issues down the line.
When you do not need the environment again, you just run this command:
cdk destroy
This will destroy all servers and other resources created.
The Digital Workstation can be as small as just a Jamulus server for the band or as big as a full virtual concert hall setup with a live console (or digital audio workstation or live mixer) and an audience following the performance on Zoom. You decide by setting the parameters for your environment.
To configure your environment you provide a file with the name config.json
and
you put it in the folder bin
of the project. If you cloned the project from
GitHub the file .gitignore
ensures you never push the file back to GitHub as
it can include some sensible information. The example-config.json
shows you
an example structure of the file.
The settings are described in the following sections.
configBucketName
- Type:
string
- Required: No
- Default:
jamulus-config-bucket
- Description: The name for the bucket where the configuration and
installation files for the EC2 instances should be hosted. This name
must be unique in the region and across all AWS Accounts. If no name is
provided it will create a bucket with the name
jamulus-config-bucket
.
keyName
- Type:
string
- Required: No, if you do not setup a
ZoomServer
. - Default: -
- Description: Provide a keyname so you can access created servers via a secure shell (i.e., SSH) or (in case of the Windows Server) to retrieve the password of the Windows machine. You first have to create a PEM key manually and store the key file locally (see details here: https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/AccessingInstancesLinux.html). You then provide the name of this key file through this parameter.
bandServerSettings
- Type:
JamulusServerSettings
- Required: Yes
- Default: -
- Description: The settings for the Jamulus server the band members connect to.
audioWorkstationSettings
- Type:
AudioWorkstationSettings
- Required: No
- Default: -
- Description: The settings for the audio workstation which is routing the signals of every band member into separate channels in a Digital Workstation (i.e., Ardour), so it can be mixed live. The mixed signal is routed to the Zoom server through the Jamulus mixing server.
mixingServerSettings
- Type:
JamulusServerSettings
- Required: No
- Default: -
- Description: The settings for the Jamulus mixing server where the mixed signal will be routed to. The Zoom server will take the signal from there to feed it into the Zoom meeting.
zoomServerSettings
- Type:
ZoomServerSettings
- Required: No
- Default: -
- Description: The settings for the Windows server where Zoom will be running. Zoom will connect to the Zoom meeting and will feed the mixed signal to it.
timezone
- Type:
string
- Required: No
- Default:
UTC
- Description: Set the timezone for your servers.
channels
- Type:
string[]
(an Array of strings) - Required: No
- Default: -
- Description: The channels that should be created in the Ardour
session (i.e., the Digital Audio Workstation). This setting also creates
the
ini
files for the Jamulus instances and adds the launch of one Jamulus instance per channel to only route the signal of such particular band member into its dedicated channel in Ardour.
Example:
channels: [
"Vocal Jane",
"Vocal Jon",
"Acoustic",
"Drums"
]
Details on the types mentioned in Settings for your Digital Workstation environment
extends StandardServerSettings
ubuntuPassword
- Type:
string
- Required: Yes
- Default: -
- Description: The password for the user
ubuntu
to be used for the RDP authentication.
detailedServerMetrics
- Type:
boolean
- Required: No
- Default: false
- Description: Provide
true
if you want to have detailed metrics about the state of your servers (i.e., memory usage, disk space etc.). The CloudWatch Agent will be installed on the server to retrieve those detailed metrics.
extends StandardServerSettings
settingsFileName
- Type:
string
- Required: No
- Default: -
- Description: If no image is provided a server settings file name should be provided. This file should be available on an S3 bucket as the user data will try to copy the file from there. The user data file will include a line comparable to the below example. So, you need to ensure the mentioned file name exists on the represented bucket.
aws s3 cp s3://jamulus-config-bucket/%%SERVER-SETTINGS-FILE-NAME%% jamulus.service
extends DetailedServerMetrics
elasticIpAllocation
- Type:
string
- Required: No
- Default: -
- Description: Provides an allocation ID for an Elastic IP so that this server will always be available under the same public IP address. Learn how to setup your Elastic IP and provide the Allocation ID in this parameter. If you do not provide an Elastic IP, everytime you redeploy or reconfigure your Digital Workstation you will have a different public IP and it will be harder for you to connect to the Audio Workstation or the Zoom Server or for your band members to connect to the Jamulus Band Server.
imageId
- Type:
string
- Required: No
- Default: A standard image for the instace type.
- Description: Provide an AMI ID if you have created an image with a running server already. This image will then be used instead of running a launch script (i.e., user data) to install and configure the server instance. If you run your rehearsals or performance always with the same team or band, you can save setup time of the whole system by creating a snapshot/image after the initialization of all servers. When you finished your session and you destroy your environment, you save costs as your not having any running servers or assigned disks and still have a fast setup time. However, the snapshot/image comes with costs and you can also only use an image if you are also using Elastic IPs to ensure your servers always have the same IP address. See details on creating an image and then provide the AMI ID in this parameter.
publicIp
- Type:
string
- Required: No
- Default: -
- Description: Provide the public IP address you generated through the Elastic IP. This is needed to create the client packages for the band members automatically.
meetingId
- Type:
string
- Required: Yes
- Default: -
- Description: The Zoom meeting ID.
password
- Type:
string
- Required: No
- Default: -
- Description: The Zoom meeting password.
extends StandardServerSettings
zoomMeeting
- Type:
ZoomMeetingProps
- Required: Yes
- Default: -
- Description: The Zoom meeting properties this instance should connect and send the mixed signal to.
TODO: to be documented as described in issue #11.
Check out the roadmap of the project on GitHub.