FriendsFM

FriendsFM is a lightweight Windows 10/11 desktop application that allows you to monitor your friends' listening habits on Last.fm in real-time. Whenever a friend starts scrobbling a new track, you'll receive a beautiful, high-quality Windows notification.

Watch your friends' music choices appear instantly on your desktop.

---

✨ Features

• System Tray Integration: Runs silently in the background. Access settings or logs via a right-click menu.

  

• Real-time Monitoring: Polling-based scrobble detection for multiple Last.fm users.

• Smart Onboarding: An interactive Setup Wizard guides you through the initial API configuration.

• Hero Notifications: Automatically processes album art into wide "Hero" images with blurred backgrounds for a premium look.

• Secure Credential Storage: Uses the Windows Credential Vault (via keyring) to store your API secrets safely—never in plain text.

• Single Instance Enforcement: Prevents multiple copies of the app from running simultaneously to save resources and avoid API rate-limiting.

• Live Status Monitor: A dedicated window to view real-time logs and connection statuses.

---

🛠️ Technology Stack

• Language: Python 3.10+
• GUI Framework: Tkinter (Custom styled)
• API Wrapper: pylast
• Image Processing: Pillow
• System Tray: pystray
• Notifications: win11toast

---

🚀 Getting Started

Prerequisites

1. Windows 10 or 11: The application is built for modern Windows environments (tested on Windows 11).
2. Python 3.10 or higher installed on your system.
3. Last.fm API Keys: You can obtain them for free at last.fm/api/account/create.

Installation

1. Clone the repository:

   git clone https://github.com/ale-enry/friendsfm
   cd friendsfm

2. Install the required dependencies:

   pip install -r requirements.txt

3. Run the application:

   python main.py

---

📦 Building the Executable

FriendsFM includes a dedicated build script to create a standalone .exe file for Windows.

1. Ensure you have Python 3.10+ installed
2. Ensure you have the assets folder with logo.ico in the root directory.
3. Run the build automation script:

   build_exe.bat

4. The final executable FriendsFM.exe will be generated in the main directory.

---

📂 Project Structure

• main.py: The entry point of the application. Handles threading and initialization.
• src/core/: Contains the business logic (Scraper, Config Manager, Notifier).
• src/ui/: Contains all GUI components (Wizard, Settings, Monitor, Tray).
• src/utils/: General utility functions for API validation, image processing, and system paths.
• src/shared.py: Global thread-safe logging and event management.
• assets/: Icons and static resources.
• docs/: Images and GIFs used for documentation and the README file.

---

🛡️ Privacy & Security

FriendsFM respects your privacy:

• Your API Key & Shared Secret are stored securely in your local Windows Vault.
• The application only performs Read-Only requests to the Last.fm API.
• No data is shared with or sent to external servers other than Last.fm.

---

⚠️ Disclaimer & Limitation of Liability

Educational Purposes Only: This software is provided for educational and personal use only.

• No Warranty: The software is provided "as is", without warranty of any kind, express or implied. The author shall not be held liable for any claim, damages, or other liability arising from the use of this software.
• Third-Party Terms: Users are solely responsible for ensuring that their use of this software complies with both the Last.fm Terms of Service and the Last.fm API Terms of Use. The author is not affiliated with, endorsed by, or supported by Last.fm.
• Intellectual Property: All album covers, artist names, and track titles displayed by the application are the property of their respective copyright owners. FriendsFM acts as a metadata viewer; it does not claim ownership over any retrieved media and does not redistribute copyrighted material for commercial purposes.

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.