From 56e3e894abecfc05c8298d25d0d8d56eac1c5cdd Mon Sep 17 00:00:00 2001 From: Mathis Maquenne <124215603+mathismqn@users.noreply.github.com> Date: Mon, 19 May 2025 16:38:36 +0200 Subject: [PATCH] docs: update README --- .example-config | 3 -- README.md | 74 ++++++++++++++++++++++++++++++------------------- 2 files changed, 45 insertions(+), 32 deletions(-) delete mode 100644 .example-config diff --git a/.example-config b/.example-config deleted file mode 100644 index c4a2db5..0000000 --- a/.example-config +++ /dev/null @@ -1,3 +0,0 @@ -arl_cookie = '1d9e90abb452a61b1b7463f0953e1b303c4e2e7e5fd404fde9b385f4de01c340ac0f62f1c8c1550405b0b9beded0e28c481e96a6148e8f4548351add5d7db746b2785ecf83b1768e5dd8cc73b1ad30c18d07c9cb37f5c6b9cd7a78a4de2aff11' -secret_key = 'hTv1IAw19qWy9i3f' -output_dir = '' diff --git a/README.md b/README.md index c747276..7020253 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,10 @@ # GoDeez +[![GitHub release](https://img.shields.io/github/v/release/mathismqn/godeez)](https://github.com/mathismqn/godeez/releases) +[![License](https://img.shields.io/github/license/mathismqn/godeez)](https://github.com/mathismqn/godeez/blob/main/LICENSE) +[![Last commit](https://img.shields.io/github/last-commit/mathismqn/godeez)](https://github.com/mathismqn/godeez/commits/main) + A simple Go tool for downloading music from [Deezer](https://www.deezer.com). [Features](#features) • @@ -18,6 +22,8 @@ A simple Go tool for downloading music from [Deezer](https://www.deezer.com). * Download playlists and albums from Deezer * Select audio quality: MP3 128kbps, MP3 320kbps, or FLAC * Automatically adds metadata tags to downloaded files +* Fetch and tag songs with BPM and musical key +* Smart skip system: avoids re-downloading already existing files using hashes and metadata * Cross-platform support (works on Windows, macOS, and Linux) * Simple and easy-to-use CLI @@ -32,26 +38,28 @@ To install **GoDeez**, simply download the latest binary for your platform from Example (Linux/macOS): ```bash # Move the downloaded binary to /usr/local/bin for easy access from anywhere -mv godeez-1.0.0-linux-amd64 /usr/local/bin/godeez +mv godeez-1.1.0-linux-amd64 /usr/local/bin/godeez ``` ## Configuration -The first time you run **GoDeez**, a configuration file named .godeez will be automatically generated in your home directory ($HOME on Linux/macOS, %USERPROFILE% on Windows). +The first time you run **GoDeez**, a configuration directory named `.godeez` will be automatically created in your home directory (`$HOME` on Linux/macOS, `%USERPROFILE%` on Windows). -This configuration file contains several important variables that you need to fill out manually. Below are the steps for retrieving and setting each variable. +Inside this directory: +- `config.toml`: main configuration file which contains several important variables that you need to fill out manually +- `tracks.db`: internal database used to track downloaded files and prevent duplicates ### Steps to configure -1. Run the application for the first time: This generates the .godeez configuration file in your home directory. -2. Edit the configuration file: Open the .godeez file with a text editor to set the required variables. +1. Run the application for the first time: this creates the `.godeez` directory and the `config.toml` file inside it. +2. Edit the `config.toml` file with a text editor to set the required values. ### Variables to configure -Here are the key variables you need to set in the .godeez file: +Here are the key variables you need to set in `config.toml`: 1. `arl_cookie` -* **What is it?**: The arl_cookie is a session cookie used for authentication with Deezer. Without this cookie, the downloader cannot access your account to retrieve playlists, albums, or songs. +* **What is it?**: The `arl_cookie` is a session cookie used for authentication with Deezer. Without this cookie, the downloader cannot access your account to retrieve playlists, albums, or songs. * **How to retrieve it**: 1. Open your browser and log in to your Deezer account. 2. Open the Developer Tools (right-click on the page and select “Inspect” or press F12). @@ -59,28 +67,31 @@ Here are the key variables you need to set in the .godeez file: 4. In the left panel, look for Cookies and select `https://www.deezer.com`. 5. Find the arl cookie and copy its value. -2. `license_token` -* **What is it?**: The license_token is required to access Deezer’s media URLs for downloading songs. This token is found in the network requests your browser makes when playing a song. -* **How to retrieve it**: - 1. Open Developer Tools in your browser (right-click on the page and select “Inspect” or press F12). - 2. Go to the Network tab. - 3. Start playing a song on Deezer and look for a request to `https://media.deezer.com/v1/get_url`. - 4. Select the request and in the Request Data section, find the license_token. - 5. Copy the license_token value. - -3. `secret_key` -* **What is it?**: The secret_key is a cryptographic value used alongside the iv to decrypt Deezer’s media files. +2. `secret_key` +* **What is it?**: The `secret_key` is a cryptographic value used to decrypt Deezer’s media files. * **How to retrieve it?**: While we cannot provide the specific secret_key in this documentation, it can be found online through various sources or developer communities that focus on Deezer. -4. `iv` -* **What is it?**: This is another cryptographic variable needed to decrypt media streams from Deezer. -* **How to retrieve it?**: The iv can be found in the [.example-config](https://github.com/mathismqn/godeez/blob/main/.example-config) file included with this project. +3. `output_dir` (optional) +* **What is it?**: The `output_dir` is the path where downloaded music files will be saved. +* **Default**: If left empty, it defaults to `~/Music/GoDeez`. +* **Note**: Once set, it's recommended not to change it, as this may interfere with the skip system that relies on consistent file paths and hash indexing to detect already downloaded songs. + +### Example + +Here's an example of a minimal `config.toml` you can customize: +```toml +# ~/.godeez/config.toml + +arl_cookie = 'your_arl_cookie_here' +secret_key = 'your_secret_key_here' +output_dir = '' # optional +``` ## Usage ### CLI Overview -When you run **godeez** without any additional commands, you’ll see a general help menu: +When you run `godeez` without any additional commands, you’ll see a general help menu: ```bash GoDeez is a tool to download music from Deezer @@ -93,7 +104,7 @@ Available Commands: help Help about any command Flags: - --config string config file (default is $HOME/.godeez) + --config string config file (default ~/.godeez/config.toml) -h, --help help for godeez Use "godeez [command] --help" for more information about a command. @@ -108,16 +119,17 @@ Usage: godeez download [command] Available Commands: - album Download songs from one or more albums - playlist Download songs from one or more playlists + album Download songs from album + playlist Download songs from playlist Flags: - -h, --help help for download - -o, --output string output directory (default is current directory) - -q, --quality string download quality [mp3_128, mp3_320, flac, best] (default is best) + --bpm fetch BPM/key and add to file tags + -h, --help help for download + -q, --quality string download quality [mp3_128, mp3_320, flac, best] (default "best") + -t, --timeout duration timeout for each download (e.g. 10s, 1m, 2m30s) (default 2m0s) Global Flags: - --config string config file (default is $HOME/.godeez) + --config string config file (default ~/.godeez/config.toml) Use "godeez download [command] --help" for more information about a command. ``` @@ -133,3 +145,7 @@ Every bit of support counts, so don’t forget to give the project a star if you ## License This project is licensed under the MIT License. See the [LICENSE](https://github.com/mathismqn/godeez/blob/main/LICENSE) file for details. + +--- + +> ⚠️ This tool is provided for educational and personal use only. Please ensure your usage complies with Deezer’s Terms of Service. \ No newline at end of file