scrobble: repo start with 0.1.0 release on PyPI.

sheriferson · Aug 3, 2023 · 79ef3a9 · 79ef3a9
commit 79ef3a9
Show file tree

Hide file tree

Showing 19 changed files with 1,425 additions and 0 deletions.
diff --git a/.gitignore b/.gitignore
@@ -0,0 +1,2 @@
+build
+dist
diff --git a/CHANGES b/CHANGES
@@ -0,0 +1,10 @@
+0.1.0 (2023-08-02):
+    * Initial release on GitHub and PyPI.
+    * `scrobble` is intended to be a general/omni-scrobbling tool that works with different tracklists.
+    * To start, `scrobble` works with CD barcodes.
+    * Supports multi disc releases.
+    * Uses MusicBrainz as the source of CD and track metadata.
+    * Accepts an optional `PLAYBACKEND` argument in natural language if you want to scrobble a CD you listened to a while ago. e.g., `scrobble 016861828257 '2 hours ago'`.
+    * A `--dryrun` option if you just want to see a tracklist without sending anything to your last.fm account.
+    * A `--notify` option if you want to get a Pushover.net notification. Requires a Pushover app API token and a user key.
+    * If the barcode matches more than one release, the tool will ask you to choose. This matters because sometimes the tracklist is different (how releases that different end up with the same barcode is... pfff I don't know). If you want to yolo it, you can pass `--no-choice` and have the tool pick the first match.
diff --git a/LICENSE.txt b/LICENSE.txt
diff --git a/MANIFEST.in b/MANIFEST.in
@@ -0,0 +1,3 @@
+include README.md LICENSE.txt CHANGES
+include requirements.txt
+include *.toml
diff --git a/README.md b/README.md
@@ -0,0 +1,163 @@
+# Scrobble
+
+A little very unofficial Python CLI tool to scrobble music to Last.fm.
+
+> **Note**
+> Super early, under active development, and so forth.
+
+
+## Background
+
+It started as a tool to scrobble CD tracklists using barcodes, and that's what it does today, but there are plans for it to do more.
+
+Inspired by [CodeScrobble][] and [Open Scrobbler][].
+
+[CodeScrobble]: https://codescrobble.com "CodeScrobble tool for scanning CD or record barcodes and scrobbling the tracklist."
+[Open Scrobbler]: https://openscrobbler.com "Open Scrobbler tool for scrobbling albums or custom tracks."
+
+## Features
+
+- Scrobble a CD's tracklist using its barcode.
+- Supports multi disc releases.
+- Uses MusicBrainz as the source of CD and track metadata.
+- Accepts an optional `PLAYBACKEND` argument in natural language if you want to scrobble a CD you listened to a while ago. e.g., `scrobble 016861828257 '2 hours ago'`.
+- A `--dryrun` option if you just want to see a tracklist without sending anything to your last.fm account.
+- A `--notify` option if you want to get a Pushover.net notification. Requires a Pushover app API token and a user key.
+- If the barcode matches more than one release, the tool will ask you to choose. This matters because sometimes the tracklist is different (how releases that different end up with the same barcode is... pfff I don't know). If you want to yolo it, you can pass `--no-choice` and have the tool pick the first match.
+
+## Installation
+
+```sh
+pip3 install scrobble
+```
+
+or
+
+```sh
+git clone https://github.com/sheriferson/scrobble
+cd scrobble
+pip3 install .
+```
+
+## Configuration
+
+Okay you need to do some configuration before this will do anything useful for you. Some configurations are required (last.fm) and others are optional (Pushover).
+
+You need to [get a last.fm API account][lastfmapi]. It's easy and immediate. Once you have a key and a secret, put them in `~/.config/cdscrobble.toml`:
+
+[lastfmapi]: https://www.last.fm/api/account/create "Create a last.fm API account."
+
+**Below is the mininum required configuration for this tool to work.**
+```toml
+[lastfmapi]
+api_key = '<your-api-key>'
+api_secret = '<your-api-secret>'
+username = '<optional-username-for-url-in-pushover-notification>'
+```
+
+The first time you try to scrobble something, the app will ask you to give it permission to connect to your last.fm account, so you will need access to the machine's screen/browser. Once this is done, it will save a session key in `~/.lastfm_session_key`, and shouldn't need to ask for permission again.
+
+If you want this tool to run on a remote/headless server, you can run the tool once on your local machine, then copy `~/.config/.lastfm_session_key` over your remote host.
+
+If you plan on using `--notify` to get notifications when scrobbling is complete, you need to provide a Pushover API token and user key as well:
+
+
+```toml
+[pushoverapi]
+token = '<your-pushover-app-token>'
+user = '<your-user-key>'
+```
+
+## Usage
+
+```sh
+scrobble --help
+```
+
+```sh
+ Usage: scrobble [OPTIONS] BARCODE [PLAYBACKEND]
+
+╭─ Arguments ──────────────────────────────────────────────────────────────────────────────╮
+│ *    barcode          TEXT           Barcode of the CD you want to scrobble. Double      │
+│                                      album releases are supported.                       │
+│                                      [default: None]                                     │
+│                                      [required]                                          │
+│      playbackend      [PLAYBACKEND]  When did you finish listening? e.g., 'now' or '1    │
+│                                      hour ago'.                                          │
+│                                      [default: now]                                      │
+╰──────────────────────────────────────────────────────────────────────────────────────────╯
+╭─ Options ────────────────────────────────────────────────────────────────────────────────╮
+│ --dryrun                --no-dryrun       --dryrun will print a list of tracks without   │
+│                                           scrobbling to last.fm                          │
+│                                           [default: no-dryrun]                           │
+│ --verbose               --no-verbose      --verbose will print a bunch of stuff to your  │
+│                                           terminal.                                      │
+│                                           [default: no-verbose]                          │
+│ --notify                --no-notify       --notify will send a push notification via     │
+│                                           Pushover with CD information.                  │
+│                                           [default: no-notify]                           │
+│ --install-completion                      Install completion for the current shell.      │
+│ --show-completion                         Show completion for the current shell, to copy │
+│                                           it or customize the installation.              │
+│ --help                                    Show this message and exit.                    │
+╰──────────────────────────────────────────────────────────────────────────────────────────╯
+
+```
+
+## Examples
+
+```sh
+# list album info and tracks from Rammstein's Herzeleid without actually scrobbling
+
+$ scrobble --dryrun --verbose 031452916021
+
+💿 Rammstein - Herzeleid (1996)
+🎵 1 Wollt ihr das Bett in Flammen sehen?
+🎵 2 Der Meister
+🎵 3 Weißes Fleisch
+🎵 4 Asche zu Asche
+🎵 5 Seemann
+🎵 6 Du riechst so gut
+🎵 7 Das alte Leid
+🎵 8 Heirate mich
+🎵 9 Herzeleid
+🎵 10 Laichzeit
+🎵 11 Rammstein
+⚠️  Dry run - no tracks were scrobbled.
+
+
+# scrobble Nymphetamine by Cradle of Filth which you finished
+# listening to two hours ago
+
+$ scrobble 016861828257 '2 hours ago'
+
+# scrobble Comalies by Lacuna Coil
+# the barcode matches multiple releases, so you're offered options
+
+$ scrobble 727701816029
+
+More than one release matches barcode 727701816029.
+
+1. Comalies, 1 disc, 13 tracks, released in 2002.
+2. Comalies, 2  discs, 22 tracks, released in 2004.
+3. Comalies, 1 disc, 13 tracks, released in 2002.
+
+Which release do you want to scrobble? [1/2/3] (1):
+...
+# as you can see, sometimes there are duplicates
+# differentiation between them isn't handled very well right now
+
+# scrobble Fight Club: Original Motion Picture Score
+# barcode matches multiple releases, but  don't ask me to choose a release,
+# just pick the first one and send a notification using
+# pushover.net (requires extra configuration)
+
+$ scrobble --no-choice --notify 018777371520
+```
+
+
+## Missing
+
+- Tests.
+- Docs.
+- Other features.
diff --git a/pyproject.toml b/pyproject.toml
@@ -0,0 +1,31 @@
+[build-system]
+requires = ["setuptools", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "scrobble"
+version = "0.1.0"
+description = "Scrobble CDs to your last.fm account."
+readme = "README.md"
+authors = [{ name = "Sherif Soliman", email = "[email protected]" }]
+license = { file = "LICENSE" }
+keywords = ["last.fm", "scrobble", "cd", "music"]
+requires-python = ">=3.11"
+classifiers = [
+    "Topic :: Utilities",
+    "Programming Language :: Python :: 3",
+]
+dependencies = [
+    "musicbrainzngs",
+    "parsedatetime",
+    "pylast",
+    "python-dateutil",
+    "rich",
+    "typer[all]",
+]
+
+[project.urls]
+Homepage = "https://github.com/sheriferson/scrobble"
+
+[project.scripts]
+scrobble = "scrobble.app:main"
diff --git a/requirements.txt b/requirements.txt
@@ -0,0 +1,6 @@
+musicbrainzngs
+parsedatetime
+pylast
+python-dateutil
+rich
+typer[all]
diff --git a/src/scrobble.egg-info/PKG-INFO b/src/scrobble.egg-info/PKG-INFO
@@ -0,0 +1,172 @@
+Metadata-Version: 2.1
+Name: scrobble
+Version: 0.1
+Summary: Scrobble CDs to your last.fm account.
+Author-email: Sherif Soliman <[email protected]>
+Project-URL: Homepage, https://github.com/sheriferson/scrobble
+Keywords: last.fm,scrobble,cd,music
+Classifier: Topic :: Utilities
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+
+# Scrobble
+
+A little very unofficial Python CLI tool to scrobble music to Last.fm.
+
+> **Note**
+> Super early, under active development, and so forth.
+
+
+## Background
+
+It started as a tool to scrobble CD tracklists using barcodes, and that's what it does today, but there are plans for it to do more.
+
+Inspired by [CodeScrobble][] and [Open Scrobbler][].
+
+[CodeScrobble]: https://codescrobble.com "CodeScrobble tool for scanning CD or record barcodes and scrobbling the tracklist."
+[Open Scrobbler]: https://openscrobbler.com "Open Scrobbler tool for scrobbling albums or custom tracks."
+
+## Features
+
+- Scrobble a CD's tracklist using its barcode.
+- Supports multi disc releases.
+- Uses MusicBrainz as the source of CD and track metadata.
+- Accepts an optional `PLAYBACKEND` argument in natural language if you want to scrobble a CD you listened to a while ago. e.g., `scrobble 016861828257 '2 hours ago'`.
+- A `--dryrun` option if you just want to see a tracklist without sending anything to your last.fm account.
+- A `--notify` option if you want to get a Pushover.net notification. Requires a Pushover app API token and a user key.
+- If the barcode matches more than one release, the tool will ask you to choose. This matters because sometimes the tracklist is different (how releases that different end up with the same barcode is... pfff I don't know). If you want to yolo it, you can pass `--no-choice` and have the tool pick the first match.
+
+## Installation
+
+`pip install` coming soon.
+
+```sh
+git clone https://github.com/sheriferson/scrobble
+cd scrobble
+pip3 install .
+```
+
+## Configuration
+
+Okay you need to do some configuration before this will do anything useful for you. Some configurations are required (last.fm) and others are optional (Pushover).
+
+You need to [get a last.fm API account][lastfmapi]. It's easy and immediate. Once you have a key and a secret, put them in `~/.config/cdscrobble.toml`:
+
+[lastfmapi]: https://www.last.fm/api/account/create "Create a last.fm API account."
+
+**Below is the mininum required configuration for this tool to work.**
+```toml
+[lastfmapi]
+api_key = '<your-api-key>'
+api_secret = '<your-api-secret>'
+username = '<optional-username-for-url-in-pushover-notification>'
+```
+
+The first time you try to scrobble something, the app will ask you to give it permission to connect to your last.fm account, so you will need access to the machine's screen/browser. Once this is done, it will save a session key in `~/.lastfm_session_key`, and shouldn't need to ask for permission again.
+
+If you want this tool to run on a remote/headless server, you can run the tool once on your local machine, then copy `~/.config/.lastfm_session_key` over your remote host.
+
+If you plan on using `--notify` to get notifications when scrobbling is complete, you need to provide a Pushover API token and user key as well:
+
+
+```toml
+[pushoverapi]
+token = '<your-pushover-app-token>'
+user = '<your-user-key>'
+```
+
+## Usage
+
+```sh
+scrobble --help
+```
+
+```sh
+ Usage: scrobble [OPTIONS] BARCODE [PLAYBACKEND]
+
+╭─ Arguments ──────────────────────────────────────────────────────────────────────────────╮
+│ *    barcode          TEXT           Barcode of the CD you want to scrobble. Double      │
+│                                      album releases are supported.                       │
+│                                      [default: None]                                     │
+│                                      [required]                                          │
+│      playbackend      [PLAYBACKEND]  When did you finish listening? e.g., 'now' or '1    │
+│                                      hour ago'.                                          │
+│                                      [default: now]                                      │
+╰──────────────────────────────────────────────────────────────────────────────────────────╯
+╭─ Options ────────────────────────────────────────────────────────────────────────────────╮
+│ --dryrun                --no-dryrun       --dryrun will print a list of tracks without   │
+│                                           scrobbling to last.fm                          │
+│                                           [default: no-dryrun]                           │
+│ --verbose               --no-verbose      --verbose will print a bunch of stuff to your  │
+│                                           terminal.                                      │
+│                                           [default: no-verbose]                          │
+│ --notify                --no-notify       --notify will send a push notification via     │
+│                                           Pushover with CD information.                  │
+│                                           [default: no-notify]                           │
+│ --install-completion                      Install completion for the current shell.      │
+│ --show-completion                         Show completion for the current shell, to copy │
+│                                           it or customize the installation.              │
+│ --help                                    Show this message and exit.                    │
+╰──────────────────────────────────────────────────────────────────────────────────────────╯
+
+```
+
+## Examples
+
+```sh
+# list album info and tracks from Rammstein's Herzeleid without actually scrobbling
+
+$ scrobble --dryrun --verbose 031452916021
+
+💿 Rammstein - Herzeleid (1996)
+🎵 1 Wollt ihr das Bett in Flammen sehen?
+🎵 2 Der Meister
+🎵 3 Weißes Fleisch
+🎵 4 Asche zu Asche
+🎵 5 Seemann
+🎵 6 Du riechst so gut
+🎵 7 Das alte Leid
+🎵 8 Heirate mich
+🎵 9 Herzeleid
+🎵 10 Laichzeit
+🎵 11 Rammstein
+⚠️  Dry run - no tracks were scrobbled.
+
+
+# scrobble Nymphetamine by Cradle of Filth which you finished
+# listening to two hours ago
+
+$ scrobble 016861828257 '2 hours ago'
+
+# scrobble Comalies by Lacuna Coil
+# the barcode matches multiple releases, so you're offered options
+
+$ scrobble 727701816029
+
+More than one release matches barcode 727701816029.
+
+1. Comalies, 1 disc, 13 tracks, released in 2002.
+2. Comalies, 2  discs, 22 tracks, released in 2004.
+3. Comalies, 1 disc, 13 tracks, released in 2002.
+
+Which release do you want to scrobble? [1/2/3] (1):
+...
+# as you can see, sometimes there are duplicates
+# differentiation between them isn't handled very well right now
+
+# scrobble Fight Club: Original Motion Picture Score
+# barcode matches multiple releases, but  don't ask me to choose a release,
+# just pick the first one and send a notification using
+# pushover.net (requires extra configuration)
+
+$ scrobble --no-choice --notify 018777371520
+```
+
+
+## Missing
+
+- Tests.
+- Docs.
+- Other features.