xdgfx/ultrasonics-api repository overview

⁠The api proxy for ultrasonics.

This is the source code for the ultrasonics-api proxy server. It's purpose is to store private api keys for services such as Spotify, Deezer, and Last.fm, while providing an endpoint for ultrasonics to access those apis.

⁠Option 0: Use the official hosted ultrasonics-api.

There is an official hosted version at https://ultrasonics-api.herokuapp.com/api/⁠. Feel free to use that instead of hosting your own version. Therefore, no setup is required, and you can get started on curating your perfect playlists. Or you can run it yourself, it's up to you 😊.

⁠Option 1: Host your own Heroku instance.

Just click the button below! Make sure you refer to environment variables⁠.

Or do it manually 😉: Follow the official instructions⁠ after cloning this repo. You will need to use the environment variable USE_REDIS=True and also set up a Heroku Redis instance⁠.

🌤️ This is actually a lot easier than those tutorials appear on first glance, you just need to create them both and get the correct URLs.

You can set up environment variables according to the official documentation⁠. See environment variables⁠.

⁠Option 2: Use the official docker image.

Either make the image using the Dockerfile, or pull from the official repo: XDGFX/ultrasonics-api.

Recommended usage: docker-compose

version: "3.7"
services:
  ultrasonics-api:
    image: xdgfx/ultrasonics-api
    container_name: ultrasonics-api
    restart: unless-stopped

    ports:
      - 8003:8003

    environment:
      - PUID=${PUID}
      - PGID=${PGID}

      - SPOTIFY_CLIENT_ID=abc
      - SPOTIFY_CLIENT_SECRET=xyz

      - LASTFM_API_KEY=xyz

      - DEEZER_APP_ID=abc
      - DEEZER_APP_SECRET=xyz

⁠Option 3: Host ultrasonics-api on your own hardware (or a virtual machine).

1. Clone the repo to your computer.
2. I would recommend creating a virtual environment (python3 -m venv .venv to create an environment in the folder .venv, then activate it with source .venv/bin/activate).
3. Install the Python dependencies with pip3 install -r requirements.txt.
4. Create a .env file, and fill it with the required environment variables. See environment variables⁠.
5. You can run your own Redis instance and connect to it, but if you're not threaded you might as well disable it with USE_REDIS = False for a cleaner install.
6. Run it by executing app.sh. You may prefer to run it as a service instead⁠.

⁠Environment Variables

These environment variables can be applied to your Heroku instance, or saved in a .env file in this directory.

If you don't use a service, you can remove it's environment variables.

Most services require you to get an api key / secret by creating an account and setting up an application. Documentation for each service can be found below.

⁠Finding API Keys

⁠.env file

FLASK_APP=ultrasonics_api

USE_REDIS=False
REDIS_URL=[Only if USE_REDIS=True]

SPOTIFY_CLIENT_ID=abc
SPOTIFY_CLIENT_SECRET=xyz

LASTFM_API_KEY=abc

DEEZER_APP_ID=abc
DEEZER_APP_SECRET=xyz