This repository has been archived by the owner on Sep 10, 2024. It is now read-only.
Quick Start Guide
These instructions are limited to the quickest/simplest way to get started with Raspberry Jam. There are other options/ways to do things for sure, but this should be the most painless way in our experience.
- Raspberry Pi 4
- MicroSD Card (see compatible SD card list here)
- MicroSD Card Reader (optional - for installing Raspberry Jam if your computer doesn't have a sdcard slot)
- 5.1V 3A USB-C for Pi 4
- Soundcard - Either Fe-pi or Audio Injector Stereo. Both Fe-pi and Audio Injector stereo have line-in and line-out, and they are about the same price. The main difference is that the Fe-pi has a headset mic input and the Audio Injector has an onboard mic. If you'd like to use a headset, I'd recommend the Fe-pi. If you want to pick up the sound of your room without an external mic, I'd recommend the Audio Injector.
- Ethernet cable for connection to your router (Wifi is not an option)
- Download the latest Raspberry Jam SD card image from here
- Once you have downloaded your SD card image you need to extract it using a program such as 7-zip. You will extract the downloaded .gz file and the extracted file will be a .img file.
- To extract from the command line, you can type the following into a Terminal window, placing X with version you downloaded:
gunzip rjam-rt-X.X.img.gz
- To install the Raspberry Jam SD image on your MicroSD card. (You may need a MicroSD card reader to plug it into your computer)
- For Windows you can use a Etcher, Win32DiskImager or Raspberry Pi Imager
- For macOS you can use Etcher, Apple Pi Baker or Raspberry Pi Imager
- For Linux you can use dd command, Etcher or Raspberry Pi Imager
- See the official Raspberry Pi "WRITING AN IMAGE TO THE SD CARD" instructions
- Install the soundcard on the GPIO header of the Raspberry Pi
- Install the SD card
- Connect the Pi to your router with the ethernet cable
- Connect headphones and any other necessary audio connections (line-in/line out for example, if not using onboard mic)
- Connect power supply to the Pi
-
The app used to control Raspberry Jam is based on the Blynk platform. You will need to download/install the Blynk app on a mobile device from the Apple/Google play store and create a Blynk account.
-
From your mobile device, click here and save the image to your device.
-
From the Blynk app, complete the following steps:
-
You should get an email from Blynk containing an Auth Token for the project. Copy the Auth Token for use in the next section.
- Power up your Raspberry Jam and allow about 30 seconds for it to boot up.
- From a device on the same network as your Pi, navigate to http://raspberryjam.herokuapp.com/
- Take note of your public IP address at the top of the page, any peers connecting to you as a client will need your public IP address.
- You should see your Pi listed, click the link under location. This should bring you to the Raspberry Jam Configurator website.
- Paste your Blynk Auth Token in the appropriate field
- Select your soundcard from the drop down menu
- Click the 'Save' button
- The Pi will reboot, and afterwards the Blynk app should indicate a connection and the app should be ready to use.
- All peers, except for one, need to setup port forwarding. A single peer can always act as a 'client' and avoid port forwarding. If there is a user in your group that isn't particularly tech savy, they would make a good candidate to always act as a 'client' and avoid port forwarding.
- Setup port forwarding on a range of ports from 4464-5000 to the local IP address of the Pi on your home router. You can find the IP address your Pi at http://raspberryjam.herokuapp.com/
- Specific instructions on how to do this vary by router, and the plan is to eventually eliminate this step completely. In the meantime unfortunately, users that will be acting as 'servers' will need to investigate how to set this up on their router.
- The app currently supports 3 connections for a total of 4 peers in a session
- Each connection will be between a 'server' and a 'client'
- Lets start with a simple 2 way connection.
- First decide on a sample rate and select the sample rate from the drop down menu. Both peers must set the same sample rate.
- Press the edit button for Connection 0.
- In the left text box, enter the name of the peer you are connecting with and press enter
- In the right text box, enter the public IP address of your peer (they should have this information from the Configure step, if not it can be found at http://raspberryjam.herokuapp.com/). Add a colon ( : ) after the IP address and enter a port offset (each connection requires a unique port), in this case since we only have a single connection we will use 0. An example entry would be 127.0.0.1:0. Press enter when the information is correct.
- Press the edit button for Connection 0 since we are finished editing the connection.
- Decide with your peer who will be the 'server' and who will be the 'client', set the Role button for Connection 0 accordingly.
- At the bottom of the screen, use the Input Select box to select whether you are using the Mic or Line input on the soundcard for your audio source.
- With the connection all setup, both peers can press the Start button for Connection 0.
- When the connection is established you should hear audio from your peer. If you do not, verify that the Input and Output level sliders are set appropriately.
- Once both peers can hear one another, you may need to adjust the Latency setting. It can be lowered to reduce latency, which may introduce audio artifacts, or increased to reduce audio artifacts. Each peer can adjust Latency independently to achieve the desired Latency/Audio quality.
- Adjust the levels of yourself and your peer(s) to comfortable levels
- If you are using the Mic input of the soundcard you can also adjust the Mic gain switch at the bottom of the page to aid in achieving the desired levels
- Jam away!
- To save the session for future use, press the save session, enter a name for the session in the text box and press enter.
- To load a saved session, select it from the Load Session selection box.
- If you need to disconnect from a peer, you can do so by pressing and holding the Start/Restart button
- Re-selecting the sample rate will re-start Jack, which may help in some troubleshooting situations
- Latency can be adjusted at any point during a session, and will restart the connection
- In order to measure the latency of a connection, the client should press the 'Test' button to enable a loopback to the Server. The Server participant can then press test and should get a result of the latency of the connection displayed in the edit boxes. When the test is complete the client can press 'Test' again to disable the loopback.
