Revamp README.md

Reformated Added a simple description (partially copied from command tool description) Added a ToC Added a simple first steps: install python, install deezer-downloader, first setup, ... Renamed some points
kmille · Nov 24, 2024 · d24260e · d24260e
1 parent 24c36eb
commit d24260e
Showing 1 changed file with 102 additions and 39 deletions.
diff --git a/README.md b/README.md
@@ -1,21 +1,86 @@
-## Music Downloader 🎶 🎧 💃 🦄
+# Deezer Downloader 🎶 🎧 💃 🦄
 [![tests](https://github.com/kmille/deezer-downloader/actions/workflows/tests.yaml/badge.svg)](https://github.com/kmille/deezer-downloader/actions/workflows/tests.yaml)
 ![latest tag](https://img.shields.io/github/v/tag/kmille/deezer-downloader?sort=semver) ![Python 3.9](https://img.shields.io/badge/python-%3E=3.9-blue.svg) ![pypi-version](https://img.shields.io/pypi/v/deezer-downloader) ![pypi-downloads](https://img.shields.io/pypi/dm/deezer-downloader)
 
-### Features
+### Download music from Deezer and Spotify with a simple web frontend, through a local-hosted service written in Python.
 
+### Features
 - download songs, albums, public playlists from Deezer.com (account is required, free plan is enough)
 - download Spotify playlists (by parsing the Spotify website and download the songs from Deezer)
 - download as zip file (including m3u8 playlist file)
-- ~~320 kbit/s~~ (currently only 128 kbit/s, see [this issue](https://github.com/kmille/deezer-downloader/issues/66#issuecomment-2002309521)) mp3s with ID3-Tags and album cover
+- ~~320 kbit/s~~ (currently only 128 kbit/s, see [this issue](https://github.com/kmille/deezer-downloader/issues/66#issuecomment-2002309521)) MP3s with ID3-Tags and album cover
+  - **UPDATE 2024/11**: It seems like 320 kbit/s MP3s and FLAC [works again](https://github.com/kmille/deezer-downloader/pull/111)
 - download songs via yt-dlp
 - KISS (keep it simple and stupid) front end
 - MPD integration (use it on a Raspberry Pi!)
 - simple REST api
 - proxy support (https/socks5)
 
+## Table of Contents:
+- [Get started](#get-started)
+  - [Install Python](#1-install-python)
+  - [Install deezer-downloader](#2-install-deezer-downloader)
+  - [Retrieve your arl cookie](#3-retrieve-your-arl-cookie)
+  - [Set the config file](#4-set-the-config-file)
+  - [Run deezer-downloader](#5-run-deezer-downloader)
+  - [Access the frontend](#6-access-the-frontend)
+- [Settings](#settings)
+- [Specific use cases](#specific-use-cases)
+  - [Run with Docker](#run-with-docker)
+  - [Run with Vagrant](#run-with-vagrant)
+  - [Run as a service](#run-as-a-service)
+  - [Developer setup](#developer-setup)
+  - [Deployment with Ansible](#deployment-with-ansible)
+- [Screenshots](#screenshots)
+- [Tests](#tests)
+- [Changelog](#changelog)
+
+## Get started
+
+### 1. Install Python
+[Here.](https://www.python.org/about/)
+
+### 2. Install deezer-downloader
+```bash
+pip install --user deezer-downloader
+```
+
+If you want to use the Docker image, [scroll](#run-with-docker) down a bit.
+
+### 3. Retrieve your `arl` cookie
+
+On Firefox or Chrome-based browser:
+- Log into your **FREE** Deezer account (do **NOT** use a premium account)
+- Open the DevTools (`F12` or `Ctrl+Shift+C` or `Ctrl+Shift+I`)
+- Go to `Storage` tab
+- In the cookies, find `arl`: a ~200 characters alphanumeric key
+
+### 4. Set the config file
+Retrieve the template: 
+```bash 
+deezer-downloader --show-config-template > config.ini
+```
+You need to set at least:
+- under `[deezer]`: `cookie_arl`, your **NON PREMIUM** arl key
+- under `[youtubedl]`: `command`, your yt-dlp install path\
+As stated in the config template, deezer-downloader do NOT keep yt-dlp updated, you will have to monitor this yourself.
+
+Check [Settings](#settings) for further instructions.
+
+### 5. Run deezer-downloader
+```bash
+deezer-downloader --config config.ini
+```
 
-### How to use it
+### 6. Access the frontend
+Unless specified differently in the config file, the default frontend address is: http://localhost:5000.
+Access it with your favourite web browser.
+
+Check [Screenshots](#screenshots) if needed.
+
+Enjoy! 🦄
+
+## Settings
 
 There is a settings file template called `settings.ini.example`. You can specify the download directory with  `download_dir`. Pressing the download button only downloads the song/album/playlist. If you set `use_mpd=True` in the `settings.ini` the backend will connect to mpd (localhost:6600) and update the music database. Pressing the play button will download the music. If `use_mpd=True`  is set the mpd database will be updated and the song/album/playlist will be added to the playlist. In `settings.ini` `music_dir` should be the music root location of mpd. The `download_dir` must be a subdirectory of `music_dir`. 
 
@@ -34,7 +99,6 @@ options:
                         show config template. At least you have to insert the ARL cookie
   -c CONFIG, --config CONFIG
                         config file - if not supplied, the following directories are considered looking for deezer-downloader.ini: current working directory, XDG_CONFIG_HOME environment variable, ~/.config, /etc)
-kmille@linbox:deezer-downloader
 
 kmille@linbox:deezer-downloader poetry run deezer-downloader --config settings.ini
 Starting Threadpool
@@ -51,23 +115,22 @@ Setting state to mission accomplished to worker 0
 worker 0 is done with task: {'track_id': 8086130, 'add_to_playlist': False} (state=mission accomplished)
 ```
 
+## Specific use cases
 
-### How to get it up and running
-#### with pip
-You can run `pip install --user deezer-downloader`. Then you can run `~/.local/bin/deezer-downloader --help`
+### Run with Docker
 
-#### with Docker
-You can use the Docker image hosted on [hub.docker.com](https://hub.docker.com/r/kmille2/deezer-downloader). Login into your **free** Deezer account and grab the `arl` cookie. Then:
+There is a Docker image hosted on [hub.docker.com](https://hub.docker.com/r/kmille2/deezer-downloader). Please use an ARL cookie of an account with a free subscription.
 
 ```bash
 mkdir downloads
-sudo docker run -p 5000:5000 --volume $(pwd)/downloads/:/mnt/deezer-downloader --env DEEZER_COOKIE_ARL=changeme kmille2/deezer-downloader:latest 
+sudo docker run -p 5000:5000 --volume $(pwd)/downloads/:/mnt/deezer-downloader --env DEEZER_COOKIE_ARL=your_ARL_cookie kmille2/deezer-downloader:latest 
 xdg-open http://localhost:5000
 ```
 
-#### with Vagrant
+### Run with Vagrant
 
 ```bash	
+cd deployment
 vagrant up
 vagrant ssh
 sudo vim /opt/deezer/settings.ini # insert your Deezer cookie
@@ -78,20 +141,18 @@ xdg-open http://localhost:5000 # view frontend in the browser
 ncmpcpp -h 127.0.0.1 # try the mpd client
 ```
 
-#### as a service
-
-We use it with nginx and [ympd](https://github.com/notandy/ympd) as mpd frontend
+### Run as systemd service
 
+We use it with nginx and [ympd](https://github.com/notandy/ympd) as mpd frontend:
 - / goes to ympd
 - /d/ goes to the downloader
 
 The deployment directory contains a systemd unit file and a nginx vhost config file. There is also a [patch](https://github.com/kmille/music-ansible/blob/master/roles/ympd/files/fix_header.patch) to add a link to the ympd frontend. The `debug` tab will show you the debug output of the app.Shortcuts
 
-
-
 If you want to debug or build it from source: there is a docker-compose file in the docker directory. The `docker/downloads` directory is mounted into the container and will be used as download directory. You have to check the permissions of the `docker/downloads` directory as docker mounts it with the same owner/group/permissions as on the host. The `deezer` user in the docker container has uid 1000. If you also have the uid 1000 then there should be no problem. For debugging: `sudo docker-compose build --force-rm && sudo docker-compose up`
 
-#### developer setup (tested on Ubuntu Jammy)
+### Developer setup
+Tested on Ubuntu Jammy:
 
 ```bash
   sudo apt-get update -q
@@ -122,13 +183,12 @@ If you want to debug or build it from source: there is a docker-compose file in
   # 5) Downloaded files are in /tmp/deezer-downloader
 ```
 
-ctrl-m: focus search bar  
-Enter: serach for songs   
-Alt+Enter: search for albums  
-ctrl-b: go to / (this is where our ympd is)  
-ctrl-shift-[1-7] switch tabs    
+### Deployment with Ansible
+Including mpd and ympd
+https://github.com/kmille/music-ansible (not maintained anymore)
 
-### Some screenshots
+
+## Screenshots
 
 Search for songs. You can listen to a 30 second preview in the browser.  
 
@@ -158,53 +218,56 @@ ncmpcpp mpd client.
 
 ![](/docs/screenshots/2020-05-13-212025_screenshot.png)  
 
-### Tests
+## Shortcuts
+
+`Ctrl`+`M`: focus search bar  
+`Enter`: serach for songs   
+`Alt`+`Enter`: search for albums  
+`Ctrl`+`B`: go to / (this is where our ympd is)  
+`Ctrl`+`Shift`+`[1-7]` switch tabs
+
+## Tests
 
 ```bash
 cd deezer-downloader
 DEEZER_DOWNLOADER_CONFIG_FILE=settings.ini poetry run pytest -v -s
-# if you don't setDEEZER_DOWNLOADER_CONFIG_FILE the default template file will be used. Some tests will fail because there is no valid arl_cookie.
+# If you don't set DEEZER_DOWNLOADER_CONFIG_FILE the default template file will be used. Some tests will fail because there is no valid arl_cookie.
 ```
 
-### Deployment with Ansible (including mpd and ympd)
-https://github.com/kmille/music-ansible (almost always outdated)
-
-
-
-### Changelog
+## Changelog
 
-#### Version 2.0.0 (27.03.2023)
+### Version 2.0.0 (27.03.2023)
 - use poetry as build system
 - build package and uploada to pypi
 - worker threads now "daemon threads" (they now just stop if you stop deezer-downloader)
 - update config template (remove http.debug)
 - update dependencies
 - switch to waitress (from gunicorn)
 
-#### Version 1.3.3 (27.12.2021)
+### Version 1.3.3 (27.12.2021)
 - replace youtube-dl by yt-dl
 - update third party dependencies
 
-#### Version 1.3.2 (26.11.2021)
+### Version 1.3.2 (26.11.2021)
 - fix broken deezer download functionality (#66, removes the ability to download flac quality)
 - update third party dependencies
 - update ubuntu base image for the docker container
 
-#### Version 1.3.1 (21.01.2021)
+### Version 1.3.1 (21.01.2021)
 - allow to set download quality (flac|mp3) via environment variable DEEZER_FLAC_QUALITY (#43)
 
-#### Version 1.3 (05.11.2020)
+### Version 1.3 (05.11.2020)
 
 - feature: download your favorite Deezer songs
 - automated tests with Github Actions
 - push Docker image to [hub.docker.com](https://hub.docker.com/repository/docker/kmille2/deezer-downloader/general) with Github Actions
 
-#### Version 1.2 (01.11.2020)
+### Version 1.2 (01.11.2020)
 
 - **breaking change:** now use the `arl` cookie instead of the `sid` cookie. This cookie does not expire so we don't need the background thread that keeps the session alive
 - add support for flac as download format
 
-#### Version 1.1 (13.05.2020)
+### Version 1.1 (13.05.2020)
 
 - thanks to [luelista](https://github.com/luelista) for the contribution!
 - play 30 second preview in browser