From 5037dc8fa6407e2f149c230cd327f3a88f1004a8 Mon Sep 17 00:00:00 2001
From: anon <hey@antisocial.moe>
Date: Wed, 9 Oct 2024 23:39:32 +0000
Subject: [PATCH] added readme

---
 readme.md | 77 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 77 insertions(+)

diff --git a/readme.md b/readme.md
index e69de29..95187c2 100644
--- a/readme.md
+++ b/readme.md
@@ -0,0 +1,77 @@
+# clementine scrobbler
+
+so i made this python script that reads the song playing on clementine and scrobbles it to my custom scrobbling software hosted at `antisocial.moe`. it might be overkill, but it works for me.
+
+## requirements
+
+- linux (because dbus and clementine and stuff)
+- python 3.x
+- clementine music player
+- `dbus-python`
+- `Pillow` (for image processing)
+- `requests` (for http requests)
+
+## installation
+
+install the required python packages:
+
+```bash
+pip install dbus-python Pillow requests
+```
+
+make sure you have clementine installed and running.
+
+## environment variables
+
+set the following environment variables:
+
+- `IMAGE_SERVER`: the url of your image server (for album covers)
+- `IMAGE_SERVER_AUTH`: your bearer token for the image server
+
+export them in your shell or add to your `.bashrc`:
+
+```bash
+export IMAGE_SERVER="https://.../wp-json/image-scrobble/v1"
+export IMAGE_SERVER_AUTH="your_auth_token"
+```
+
+## usage
+
+just run the script:
+
+```bash
+python clementine_scrobbler.py
+```
+
+it connects to clementine via dbus, reads the currently playing song, uploads the album art to your image server, and sends the scrobble data.
+
+## notes
+
+- only works on linux. sorry windows and mac users.
+- if clementine isn't running, it'll try to reconnect every 15 seconds.
+- this script is tailored for my setup, but you can tweak it for yours.
+
+# dbus
+
+you might need to set the following env variable while running it.
+
+`DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/1000/bus`
+
+on my linux desktop, `1000` is my current uid (`id -u`)
+
+## example
+
+here's how it looks when running:
+
+```bash
+$ python clementine_scrobbler.py
+Initializing.
+Connected to Clementine.
+Reading data from Clementine.
+Updated status to: some album - some song by some artist
+Successfully sent scrobble data to the server.
+```
+
+## disclaimer
+
+i made this for myself, but feel free to use or modify it. no promises that it'll work for you.
\ No newline at end of file