Songscribe API

Instrument Splitter & Midi Converter API for Songscribe

---

Quick Start ♫ Docker ♫ Manual Installation ♫ Attribution

Quick Start

If you've manually installed the API, run the following command to start the local server:

uvicorn moseca.api.main:app

To exit, press ctrl + C on Windows or cmd + C on Mac

Visit localhost:8000/docs for a list of all available endpoints with details, along with tools for testing the endpoint.

Documentation about the endpoints of the API can be found in DOCS.md or at Dockerhub.

Docker

This API has been Dockerized for easy deployment! If you have Docker Desktop installed you can follow along with the instructions here, otherwise you can follow the instructions for Manual Installation.

First, open up a terminal or command prompt and pull the Docker image (make sure Docker Desktop is running). Then, run the image in a container.

docker pull gabeserna/songscribe-api:latest
docker run -p 8000:8000 gabeserna/songscribe-api:latest

If you are using the Docker Desktop GUI, make sure to set the port to 8000 when creating the container.

You can check to see if the API is running by going to localhost:8000/docs.

The Docker image may take between 5-15 minutes to pull depending primarily on your network speed.

Hosting with Docker

To run the Docker container from a scratch on a Ubuntu server (for hosting), follow these instructions:

If Docker is not installed yet, run the following commands:

sudo apt-get update
sudo apt-get install -y apt-transport-https ca-certificates curl software-properties-common
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io

Then pull the image from Docker Hub (will take between 5-15 minutes depending on your network speed):

sudo docker pull gabeserna/songscribe-api:latest

Start the container and verify that it is running:

sudo docker run -d -p 8000:8000 gabeserna/songscribe-api:latest
sudo docker ps

Optional: To monitor the container's output run the following command to view logs in real-time:

sudo docker logs -f <container_id>

To exit out of real-time logs, press ctrl + C on Windows or cmd + C on Mac

Optional: Clean Up Old Containers and Images

• List all containers (including stopped ones):

  sudo docker ps -a

• Remove stopped containers:

  sudo docker rm <container_id>

• Remove unused images:

  sudo docker rmi <image_id>

Use your server's public IP address to access the application: http://<your_server_ip>:8000

If you don't know what the server's public IP address is, you can run:

curl ifconfig.me

Manual Installation

Using Python 3.12 will not work! Please use Python 3.11.

Prerequisites

• Python 3.11 installed on your system. You can download it from the official Python website.
• Git installed on your system. You can download it from the official Git website.

1. Clone the Repository

First, clone the Songscribe API repository to your local machine:

git clone https://github.com/gabe-serna/songscribe-api.git
cd songscribe-api

2. Create a Virtual Environment

Creating a virtual environment ensures that dependencies are managed separately from your global Python installation.

Windows:

1. Open PowerShell.

2. Create a virtual environment named venv:

   python -m venv venv
   

3. Activate the virtual environment:

   .\venv\Scripts\Activate
   

macOS/Linux:

1. Open your Terminal.

2. Create a virtual environment named venv:

   python3 -m venv venv
   

3. Activate the virtual environment:

   source venv/bin/activate
   

3. Set Python to Use UTF-8 Encoding

Windows:

1. Set Python to use UTF-8 encoding:

   $env:PYTHONUTF8=1
   

2. Verify that UTF-8 encoding is enabled:

   echo $env:PYTHONUTF8
   

   • The output should be 1.

macOS/Linux:

1. Set Python to use UTF-8 encoding:

   export PYTHONUTF8=1
   

2. Verify that UTF-8 encoding is enabled:

   echo $PYTHONUTF8
   

   • The output should be 1.

4. Upgrade pip and Install wheel

Before installing the project dependencies, ensure that pip is up-to-date and install wheel:

pip install --upgrade pip
pip install wheel

5. Install Project Dependencies

With the virtual environment activated and pip updated, install the required packages:

pip install -r requirements.txt

6. Run the API Server

Start the FastAPI server using Uvicorn:

uvicorn moseca.api.main:app

The server will be up and running once you see the following message in your terminal:

INFO:     Started server process [1]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

8. Access the API Documentation

Once the server is running, navigate to localhost:8000/docs in your web browser to access the interactive API documentation provided by Swagger UI.

Within the docs, you can access the endpoints very quickly which is great for testing.

Attribution

The Songscribe API is built off mainly three open source technologies:

• Moseca for stem separation and vocal isolation
  • Licensed under the MIT License.
• Basic Pitch for audio-to-MIDI conversion
  • Copyright 2022 Spotify AB and is licensed under the Apache License 2.0
• ADTOF for drum transcription
  • Licensed under the Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License CC BY-NC-SA 4.0.