Skip to content

FAQ

Jump to bottom
avelytchko edited this page Nov 17, 2025 · 2 revisions

FAQ - Frequently Asked Questions

Quick answers to common questions about foo_mac_scrobble.

General Questions

What is foo_mac_scrobble?

It's a native macOS component for foobar2000 that automatically tracks (scrobbles) the music you play to your Last.fm profile. It features offline queueing, native preferences UI, and seamless integration with the Last.fm API.

Is it free and open source?

Yes! Released under the MIT License. View the source code on GitHub.

What are the system requirements?

  • macOS 12 (Monterey) or later
  • foobar2000 for macOS v2.0 or later
  • A Last.fm account (free)
  • Last.fm API credentials (free, from Last.fm)

Does it work on Windows or Linux?

No, this is macOS-specific. It uses native Cocoa frameworks and the macOS-specific foobar2000 SDK. For Windows, use the official foo_scrobble component.

Installation & Setup

Where do I get Last.fm API credentials?

  1. Visit https://www.last.fm/api/account/create
  2. Fill out the API account form
  3. You'll receive an API Key and API Secret
  4. Enter both in the component's preferences

These credentials are required for the component to communicate with Last.fm.

Do I need to keep my browser open after authentication?

No. Once you've completed the authentication flow and see "Authenticated as: yourusername" in preferences, you can close your browser. The session persists across restarts.

Can I use this with multiple Last.fm accounts?

No. The component supports one Last.fm account at a time. To switch accounts:

  1. Clear your session: 
    rm ~/Library/foobar2000-v2/lastfm_session.json
  2. Restart foobar2000
  3. Authenticate with the new account

Scrobbling Behavior

When does a track get scrobbled?

A track is scrobbled when:

  • You've listened to at least 50% of the track (configurable)
  • OR at least 30 seconds (Last.fm minimum requirement)
  • The track has artist and title metadata

The default threshold is 50%, but you can adjust it in preferences.

What if I skip a track early?

If you skip before reaching the threshold, the track won't be scrobbled. This prevents partial listens from cluttering your Last.fm history.

Can I scrobble the same track twice?

Yes, but not in the same playback session. Each time you play a track from the beginning and reach the threshold, it's scrobbled again with a new timestamp.

What happens if I'm offline?

Tracks are queued locally in a JSON file:

~/Library/foobar2000-v2/lastfm_scrobble_queue.json

When you reconnect to the internet, the queue is automatically processed and tracks are submitted to Last.fm.

How often does the component check for queued tracks?

Every 30 seconds. If you have pending tracks and you're online, they'll be submitted within 30-60 seconds.

Can I see what's in the queue?

Yes, open the queue file:

cat ~/Library/foobar2000-v2/lastfm_scrobble_queue.json

Or enable debug logging and check the Console:

Last.fm: Queue initialized, X tracks loaded from disk

Authentication

Why do I see "Invalid API key" during authentication?

This is expected behavior. Last.fm redirects to a non-existent callback URL, which causes the error. Simply:

  1. Copy the full URL from your browser
  2. Paste it into the dialog in foobar2000
  3. Press OK

The component extracts the authentication token from the URL.

How long does my session last?

Indefinitely, unless:

  • You explicitly log out or re-authenticate
  • You revoke access on Last.fm website
  • Last.fm invalidates the session (rare)

Sessions are stored in:

~/Library/foobar2000-v2/lastfm_session.json

Can I see my session key?

Yes, it's stored in plain text in the session file:

cat ~/Library/foobar2000-v2/lastfm_session.json

Security note: This file contains your session key. Don't share it publicly, as it grants access to your Last.fm account.

What if I want to log out?

Delete the session file and restart foobar2000:

rm ~/Library/foobar2000-v2/lastfm_session.json

Privacy & Security

What data does the component collect?

The component only collects data necessary for scrobbling:

  • Track metadata (artist, title, album, etc.)
  • Playback timestamps
  • Your Last.fm username (for display in preferences)

No personal data is collected or shared beyond what's required by the Last.fm API.

Where is my data stored?

Locally on your Mac:

  • Session: ~/Library/foobar2000-v2/lastfm_session.json
  • Queue: ~/Library/foobar2000-v2/lastfm_scrobble_queue.json
  • Preferences: ~/Library/foobar2000-v2/config.sqlite

Nothing is sent anywhere except Last.fm.

Is my API Secret secure?

Your API Secret is stored in foobar2000's preferences system. It's not encrypted, but it's only accessible to:

  • You (file owner)
  • foobar2000 (reading preferences)

Keep your ~/Library folder secure with macOS user account permissions.

Can others see what I'm scrobbling?

That depends on your Last.fm privacy settings:

The component itself doesn't control visibility—Last.fm does.

Features & Functionality

Does it support "Love" / "Unlove" tracks?

Not yet. Currently, the component only supports scrobbling.

Can it update "Now Playing" in real-time?

Yes! The component updates your "Now Playing" status on Last.fm when you start playing a track. This happens immediately when playback begins, before the track reaches the scrobble threshold. Your Last.fm profile will show what you're currently listening to in real-time.

Does it work with streaming services?

Only if you're playing the streams through foobar2000. The component monitors foobar2000's playback, regardless of the source (local files, streams, etc.).

Can I scrobble to multiple services?

No, only Last.fm is supported. The component uses Last.fm's API exclusively.

Does it respect Last.fm's rate limits?

Yes. The component batches requests (up to 50 tracks) and implements proper retry logic to avoid hitting rate limits.

Troubleshooting

My tracks aren't scrobbling. What should I do?

See the comprehensive Troubleshooting Guide. Quick checks:

  1. Verify you're authenticated
  2. Enable debug logging
  3. Check the Console for errors
  4. Ensure you have internet connectivity

The component doesn't appear in my preferences. Why?

Possible causes:

  • Component not installed correctly
  • Incompatible macOS version (requires 12+)
  • foobar2000 version too old (requires v2.0+)

See Installation Guide for detailed steps.

How do I enable debug logging?

  1. Open Preferences → Tools → Last.fm Scrobbler
  2. Check "Enable Debug Logging"
  3. Open View → Console to see output

Where can I get help?

Development

How was this built?

Using:

  • C++ for core logic
  • Objective-C++ for macOS UI
  • foobar2000 SDK for integration
  • Last.fm API for scrobbling
  • Xcode for building

See Technical Overview for architecture details.

Can I contribute?

Absolutely! See the Contributing Guide for guidelines. Pull requests, bug reports, and feature requests are all welcome.

Is AI used in development?

Yes, transparently. This project is developed collaboratively with AI assistance to balance rapid prototyping and engineering quality.

Where's the source code?

https://github.com/avelytchko/foo_mac_scrobble

Comparison with Other Scrobblers

How does this compare to the official Last.fm desktop app?

Feature foo_mac_scrobble Last.fm Desktop App
foobar2000 integration ✅ Native ❌ External
Offline queueing ✅ Yes ✅ Yes
macOS native UI ✅ Yes ✅ Yes
Open source ✅ Yes ❌ No
Requires foobar2000 ✅ Yes ❌ No

How does this compare to foo_scrobble (Windows)?

This is the macOS equivalent of the Windows foo_scrobble component, with:

  • Native macOS Cocoa UI
  • Compiled for Apple Silicon + Intel
  • Uses macOS-specific APIs

Functionally similar, but platform-specific implementations.

Miscellaneous

Why does authentication require pasting a URL?

Last.fm's authentication flow expects a callback URL, but foobar2000 plugins can't easily register URL handlers. The URL-paste method is a workaround that:

  • Works reliably across macOS versions
  • Doesn't require system-level URL handler registration
  • Is simple and user-verifiable

Can I customize the scrobble threshold?

Yes! In preferences, adjust the "Scrobble after listening to" slider. Valid range: 1% to 100%.

Recommended: 50% (Last.fm's recommendation)

Does it work with Rosetta 2 (Intel apps on Apple Silicon)?

Yes. The component is a Universal Binary (arm64 + x86_64) and works natively on both Apple Silicon and Intel Macs.

How big can the offline queue get?

Theoretically unlimited, but practically:

  • Each track: ~200 bytes
  • 1000 tracks: ~200 KB
  • 10,000 tracks: ~2 MB

If your queue grows to 1000+ tracks, consider checking your network connection.

What happens if I edit the queue file manually?

You can, but be careful:

  • Use valid JSON syntax
  • Include required fields: artist, track, timestamp
  • Restart foobar2000 for changes to take effect

If the JSON is invalid, the component will log an error and start with an empty queue.

Version History

Where can I see the changelog?

See Changelog in the wiki, or view releases on GitHub.

How do I update to the latest version?

  1. Download the latest release
  2. Remove the old component via Preferences → Components
  3. Install the new component
  4. Restart foobar2000

Your session and queue are preserved during updates.

Still Have Questions?

Clone this wiki locally