Skip to content

cboin1996/songbird

Repository files navigation

songbirdcli 🐦

Music downloading client featuring mp3 or m4a tagging.

Install via Docker

To run the app via docker, you will require:

  1. docker: https://docs.docker.com/get-docker/

Note: to be gung-ho, add --pull always to any of the below commands to always receive the latest and greatest images.

First, initialize your docker volumes

make volumesinit

Note: bash or zsh aliases are provided below, assuming you clone songbird into your home directory into ~/proj/cboin1996/.

Itunes and Google Drive Integration

Macos:

alias songbirdgi="docker run -it --env-file "${HOME}"/proj/cboin1996/songbird/songbirdcli/songbirdcli/docker.env \
	-v "${HOME}"/proj/cboin1996/songbird/songbirdcli/songbirdcli/data/dump:/app/data/dump \
	-v "${HOME}"/proj/cboin1996/songbird/songbirdcli/songbirdcli/data/gdrive:/app/data/gdrive \
    -v "${HOME}"/Music/iTunes/iTunes\ Media/Automatically\ Add\ to\ Music.localized:/app/data/itunesauto \
    -v "${HOME}"/Music/Itunes/Itunes\ Media/Music:/app/data/ituneslib \
	-p 8080:8080 \
	--hostname songbird \
	--pull always \
	cboin/songbird:latest"

Windows:

Install windows sub-system for linux and setup the below alias:

alias songbirdgi="docker run -it --env-file "${HOME}"/proj/cboin1996/songbird/songbirdcli/songbirdcli/docker.env \
	-v "${HOME}"/proj/cboin1996/songbird/songbirdcli/songbirdcli/data/dump:/app/data/dump \
	-v "${HOME}"/proj/cboin1996/songbird/songbirdcli/songbirdcli/data/gdrive:/app/data/gdrive \
    -v /mnt/c/Users/*/Music/iTunes/iTunes\ Media/Automatically\ Add\ to\ Music:/app/data/itunesauto \
    -v /mnt/c/Users/*/Music/iTunes/iTunes\ Media/Music:/app/data/ituneslib \
	-p 8080:8080 \
	--hostname songbird \
	--pull always \
	cboin/songbird:latest"

Minimal configuration

By default, the app assumes itunes is installed. At minimum, create a .env file with to run without either.

In addition, you need a folder to store local files in. This folder will be passed as a volume mount to the dockerized app, as above in -v "app/data/dump":"app/data/dump", and is initialized automatically when running make volumesinit`.

ITUNES_ENABLED=False
GDRIVE_ENABLED=False

Gdrive Only

Create a .env file at the root of the project containing:

ITUNES_ENABLED=false
GDRIVE_FOLDER_ID=foo

Replace the foo with the folder id of your google drive folder. This is found in the url inside the folder when open in googledrive.

E.x: https://drive.google.com/drive/folders/foo

Follow https://developers.google.com/drive/api/quickstart/python, and place the credentials.json file at the app/data/gdrive folder at the root of the project.

alias songbirdg="docker run -it --env-file "${HOME}"/proj/cboin1996/songbird/songbirdcli/songbirdcli/docker.env \
	-v "${HOME}"/proj/cboin1996/songbird/songbirdcli/songbirdcli/data/dump:/app/data/dump \
	-v "${HOME}"/proj/cboin1996/songbird/songbirdcli/songbirdcli/data/gdrive:/app/data/gdrive \
	-p 8080:8080 \
	--hostname songbird \
	--pull always \
	cboin/songbird:latest"

Itunes Only

GDRIVE_ENABLED=false

Run

Macos:

alias songbirdi="docker run -it --env-file "${HOME}"/proj/cboin1996/songbird/songbirdcli/songbirdcli/docker.env \
        -v "${HOME}"/proj/cboin1996/songbird/songbirdcli/songbirdcli/data/dump:/app/data/dump \
        -v "${HOME}"/Music/iTunes/iTunes\ Media/Automatically\ Add\ to\ Music.localized:/app/data/itunesauto \
        -v "${HOME}"/Music/Itunes/Itunes\ Media/Music:/app/data/ituneslib \
	--pull always \
        cboin/songbird:latest"

Windows:

Install windows sub-system for linux and setup the below alias:

alias songbirdi="docker run -it --env-file "${HOME}"/proj/cboin1996/songbird/songbirdcli/songbirdcli/docker.env \
	-v "${HOME}"/proj/cboin1996/songbird/songbirdcli/songbirdcli/data/dump:/app/data/dump \
    -v /mnt/c/Users/*/Music/iTunes/iTunes\ Media/Automatically\ Add\ to\ Music:/app/data/itunesauto \
    -v /mnt/c/Users/*/Music/iTunes/iTunes\ Media/Music:/app/data/ituneslib \
	-p 8080:8080 \
	--hostname songbird \
	--pull always \
	cboin/songbird:latest"

Install as Package

To use songbirdcli as a python package, use

pip install songbirdcli

See tests for an example of configuring and running songbirdcli as a package.

For API documentation, view here

Development

To run the application locally, you can use a vscode debugger. You should also setup a .env file with the parameter RUN_LOCAL=True.

Requirements

  1. Clone songbirdcore adjacent to this project.

  2. Next, run

    export ENV=dev
    make setup
  3. Follow the outputted instructions from make setup.

  4. Next, run:

    make requirements

Note: the above command performs an editable install of songbirdcore

This allows you to edit songbirdcore locally, and have those changes directly integrated with this application when developing. To install the official stable version use

pip install songbirdcore

Debug CLI

Vscode debugger can be configured to run the cli.py file with the following .vscode/launch.json file

{
	"configurations": [
		{
			"name": "Python: Current File",
			"type": "python",
			"request": "launch",
			"program": "./songbirdcli/cli.py",
			"console": "integratedTerminal",
			"justMyCode": true,
			"envFile": "./dev.env"
		},
	]
}

Alternatively, you can simply run the app directly with

python3 songbirdcli/cli.py

Linting

To lint the app, run

make lint

Configuration

The following table summarizes the configurable parameters for the app, these can be setup in a .env file at the root of the project, and passed to docker with --env-file .env.

Variable Type Default Description
RUN_LOCAL bool False Whether to run the app locally, or configure it for running in a container
ROOT_PATH str sys.path[0] The root path to the project folder
DATA_PATH str "data" The name of the folder where app data is stored on disk
ITUNES_SEARCH_API_BASE_URL str "https://itunes.apple.com/search" The itunes search api root url
ITUNES_ENABLED bool True Whether to run with itunes integration enabled
ITUNES_FOLDER_PATH Optional[str] "itunesauto" The path to the itunes automatically add folder
ITUNES_LIB_PATH Optional[str] "ituneslib" The path to the itunes library folder
GDRIVE_ENABLED bool True Whether to run with google drive integration
GDRIVE_FOLDER_PATH Optional[str] "gdrive" Local folder for storing files destined for uploading to google drive
GDRIVE_FOLDER_ID Optional[str] "" The folder id of a cloud google drive folder
GDRIVE_AUTH_PORT int 8080 The port for oauth setup for google drive integration
LOCAL_SONG_STORE_STR str "dump" Where songs are stored locally
FNAME_DUP_KEY str "_dup" The key for naming duplicate files
FNAME_DUP_LIMIT str 8 The limit of duplicate files matching the FNAME_DUP_KEY
YOUTUBE_DL_ENABLED bool True Whether to enable the youtube download feature
YOUTUBE_RENDER_TIMEOUT int 20 The time before giving up on the render of youtube's search page
YOUTUBE_RENDER_WAIT float 0.2 The wait time before starting a render of the youtube search page
YOUTUBE_RENDER_SLEEP int 1 The wait time after initial render of youtube
YOUTUBE_HOME_URL str "https://www.youtube.com"
YOUTUBE_SEARCH_URL str "https://www.youtube.com/results"
YOUTUBE_SEARCH_TAG str "search_query" The html tag on youtubes home page linking to the html search form
YOUTUBE_SEARCHFORM_PAYLOAD dict {youtube_search_tag: ""} the payload for performing a youtube search
YOUTUBE_DL_RETRIES int 3 number of retries for youtube-dlp before giving up on a download
FILE_FORMAT str "mp3" This field is overwritten to m4a if itunes is enabled.