Skip to content

Installation Guide

Jump to bottom
avelytchko edited this page Nov 17, 2025 · 1 revision

Installation Guide

Complete installation instructions for foo_mac_scrobble, including system requirements, installation methods, and post-installation setup.

System Requirements

Operating System

  • macOS 12.0 (Monterey) or later
  • Architecture: Universal Binary (Intel x86_64 + Apple Silicon arm64)

foobar2000

Last.fm Account

Disk Space

  • Component: ~500 KB
  • Configuration files: ~10 KB
  • Queue (varies): Up to several MB for large offline queues

Network

  • Internet connection required for scrobbling
  • Offline queueing available when disconnected

Pre-Installation Checklist

Before installing, ensure you have:

  • macOS 12+ installed
  • foobar2000 for macOS installed and working
  • Last.fm account created
  • Last.fm API credentials obtained

Installation Methods

Method 1: Via foobar2000 Preferences (Recommended)

This is the easiest and safest method.

Step 1: Download the Component

  1. Visit the Releases page
  2. Download the latest release ZIP file: 
    foo_mac_scrobble-v0.x.x.zip
  3. The file will typically download to ~/Downloads/

Step 2: Extract the Archive

  1. Double-click the ZIP file in Finder
  2. Or use Terminal: 
    cd ~/Downloads
unzip foo_mac_scrobble-v0.x.x.zip
  3. You should now have: 
    foo_mac_scrobble.component/

Step 3: Install via foobar2000

  1. Open foobar2000
  2. Go to Preferences (⌘,) or foobar2000 → Preferences
  3. Navigate to Components in the left sidebar
  4. Click the "+" button in the top-right corner
  5. Browse to the extracted foo_mac_scrobble.component folder
  6. Select the folder and click Open
  7. The app will ask you to restart to complete the installation
  8. You should see the component added to the list

Step 4: Verify Installation

  1. Go to Preferences → Components
  2. Look for foo_mac_scrobble in the list
  3. Check that Status shows as "Loaded" or similar
  4. Go to Preferences → Tools
  5. Verify "Last.fm Scrobbler" appears in the menu

✅ Installation complete! Proceed to Configuration.

Method 2: Manual Installation

For advanced users who prefer manual file management.

Step 1: Download and Extract

Follow Steps 1-2 from Method 1 above.

Step 2: Copy to Components Directory

  1. Open Finder
  2. Press ⌘⇧G (Go to Folder)
  3. Enter: 
    ~/Library/foobar2000-v2/user-components/
  4. Create a new folder: 
    foo_mac_scrobble
  5. Copy the extracted foo_mac_scrobble.component folder into it

Result: The component should be at:

~/Library/foobar2000-v2/user-components/foo_mac_scrobble/foo_mac_scrobble.component/

Using Terminal (Alternative)

# Extract the archive
cd ~/Downloads
unzip foo_mac_scrobble-v1.x.x.zip

# Create directory
mkdir -p ~/Library/foobar2000-v2/user-components/foo_mac_scrobble/

# Copy component
cp -r foo_mac_scrobble.component ~/Library/foobar2000-v2/user-components/foo_mac_scrobble/

# Verify
ls -la ~/Library/foobar2000-v2/user-components/foo_mac_scrobble/

Step 3: Restart foobar2000

  1. Quit foobar2000 completely (⌘Q)
  2. Wait 5 seconds
  3. Reopen foobar2000

Step 4: Verify Installation

Follow Step 5 from Method 1.

Method 3: Build from Source

For developers or users who want to compile the component themselves.

See the complete Building from Source guide.

Quick version:

# Clone repository
git clone https://github.com/avelytchko/foo_mac_scrobble.git
cd foo_mac_scrobble

# Build with Xcode
cd foobar2000/foo_mac_scrobble
xcodebuild -project foo_mac_scrobble.xcodeproj \
  -scheme foo_mac_scrobble \
  -configuration Release \
  -derivedDataPath build

# Install
cp -r build/Build/Products/Release/foo_mac_scrobble.component \
  ~/Library/foobar2000-v2/user-components/foo_mac_scrobble/

Post-Installation Configuration

After installation, you need to configure the component.

Step 1: Open Preferences

  1. Open foobar2000
  2. Go to Preferences (⌘,)
  3. Navigate to Tools → Last.fm Scrobbler

You should see the preferences panel with fields for:

  • API Key
  • API Secret
  • Authentication button
  • Scrobble threshold slider
  • Debug logging checkbox

Step 2: Get Last.fm API Credentials

  1. Visit https://www.last.fm/api/account/create
  2. Fill out the form:
    • Application name: (e.g., "My foobar2000 Scrobbler")
    • Application description: (e.g., "Personal Last.fm scrobbler for foobar2000")
    • Application homepage: (can leave blank or use GitHub repo)
    • Callback URL: (can leave blank)
  3. Accept the Terms of Service
  4. Click Submit
  5. You'll receive:
    • API Key (32 character hex string)
    • API Secret (32 character hex string)

Save these credentials — you'll need them.

Step 3: Enter API Credentials

  1. In the Last.fm Scrobbler preferences:
  2. Paste your API Key into the first field
  3. Paste your API Secret into the second field
  4. Do NOT click Authenticate yet

Step 4: Authenticate with Last.fm

  1. Click the Authenticate button
  2. Your default browser will open to Last.fm
  3. Log in to Last.fm if not already logged in
  4. You'll see a permission request:
    • "Grant access to your application?"
    • Shows your API Key
  5. Click Yes, allow access
  6. The browser will redirect to a URL that shows: 
    Invalid API key - You must be granted a valid key by last.fm
    This is expected! Don't worry.

Step 5: Complete Authentication

  1. Copy the entire URL from your browser's address bar
    • It should look like: 
      https://www.last.fm/api/auth?token=abc123def456...
  2. Return to foobar2000
  3. A dialog should appear asking for the URL
  4. Paste the full URL into the dialog
  5. Click OK
  6. Wait a few seconds

Step 6: Verify Authentication

You should see a message in the preferences:

✅ Authenticated as: your_lastfm_username

If you see this, authentication successful!

Step 7: Configure Preferences

  • Scrobble threshold: Adjust the slider (default: 50%)
    • This is the percentage of a track you need to listen to before it's scrobbled
    • Last.fm recommends 50%
  • Debug logging: Enable if you want to see detailed console output
    • Useful for troubleshooting
    • View logs in View → Console

Step 8: Test Scrobbling

  1. Play a track in foobar2000
  2. Let it play past 50% (or your configured threshold)
  3. Wait 30-60 seconds
  4. Check your Last.fm profile: https://www.last.fm/user/your_username
  5. The track should appear in your recent tracks

🎉 Setup complete! You're now scrobbling.

Troubleshooting Installation

Component Doesn't Appear in Preferences

Possible causes:

  • Component not installed in correct location
  • foobar2000 not restarted
  • Incompatible macOS version

Solutions:

  1. Verify installation path:

    ls -la ~/Library/foobar2000-v2/user-components/foo_mac_scrobble/

    Should show foo_mac_scrobble.component/

  2. Check macOS version:

    sw_vers

    Should show macOS 12.0 or later

  3. Completely restart foobar2000:

    killall foobar2000
open /Applications/foobar2000.app

  4. Check Console for errors:

    • Open Console.app (macOS built-in)
    • Filter for "foobar2000"
    • Look for component loading errors

"Bundle format unrecognized" Error

Cause: Damaged or incomplete download

Solution:

  1. Delete the downloaded ZIP and component folder
  2. Re-download from Releases
  3. Verify the download completed successfully
  4. Extract and reinstall

Component Shows as "Failed to Load"

Possible causes:

  • Missing dependencies
  • Architecture mismatch
  • Corrupted files

Solutions:

  1. Verify you have a complete bundle:

    ls -la ~/Library/foobar2000-v2/user-components/foo_mac_scrobble/foo_mac_scrobble.component/Contents/

    Should show MacOS/ and Info.plist

  2. Check binary architecture:

    file ~/Library/foobar2000-v2/user-components/foo_mac_scrobble/foo_mac_scrobble.component/Contents/MacOS/foo_mac_scrobble

    Should show both x86_64 and arm64

  3. Remove and reinstall:

    • Remove via Preferences → Components
    • Delete the component folder
    • Reinstall fresh copy

foobar2000 Crashes After Installing Component

Rare, but possible solutions:

  1. Report the issue:
    • Open a GitHub Issue
    • Include crash logs from Console.app or Terminal.app

Permission Denied Errors

Cause: Incorrect file permissions

Solution:

# Fix permissions
chmod -R u+rwX ~/Library/foobar2000-v2/user-components/foo_mac_scrobble/

# Verify
ls -la ~/Library/foobar2000-v2/user-components/foo_mac_scrobble/

Updating the Component

Check Current Version

  1. Preferences → Components
  2. Find foo_mac_scrobble in the list
  3. Note the version number

Update Process

  1. Download the latest release
  2. Remove old version:
    • Preferences → Components
    • Select foo_mac_scrobble
    • Click "Remove" or "-" button
  3. Restart foobar2000
  4. Install new version using Method 1 or 2
  5. Restart foobar2000

Note: Your session and queue files are preserved during updates.

Automatic Update Notifications

Currently, the component doesn't check for updates automatically.

To stay informed:

  • ⭐ Star the repository on GitHub
  • 👀 Watch for new releases
  • 📢 Enable notifications for releases

Uninstalling the Component

Method 1: Via Preferences

  1. Preferences → Components
  2. Select foo_mac_scrobble
  3. Click "Remove" or "-" button
  4. Restart foobar2000

Method 2: Manual Removal

# Remove component
rm -rf ~/Library/foobar2000-v2/user-components/foo_mac_scrobble/

# Remove configuration files (optional)
rm ~/Library/foobar2000-v2/lastfm_session.json
rm ~/Library/foobar2000-v2/lastfm_scrobble_queue.json

# Restart foobar2000
killall foobar2000
open /Applications/foobar2000.app

Note: This also removes your authentication and queued scrobbles.

Clean Uninstall

To remove all traces:

# Remove component
rm -rf ~/Library/foobar2000-v2/user-components/foo_mac_scrobble/

# Remove data files
rm ~/Library/foobar2000-v2/lastfm_session.json
rm ~/Library/foobar2000-v2/lastfm_scrobble_queue.json

# Preferences are stored in foobar2000's configuration database
# They'll be ignored if component is not loaded

Multi-Computer Setup

Using the Same Account on Multiple Macs

You can install the component on multiple Macs with the same Last.fm account.

Each Mac needs:

  • Separate API credentials (or share the same ones)
  • Separate authentication (each Mac gets its own session key)

To set up:

  1. Install component on Mac #1 and authenticate
  2. Install component on Mac #2 and authenticate
  3. Both will scrobble to the same Last.fm profile

Note: If you scrobble the same track on both Macs simultaneously, it may create duplicates on Last.fm.

Syncing Configuration

If you want the same settings across Macs, you can sync the preferences:

Not recommended for session/queue files (can cause conflicts), but you can sync:

  • API Key and Secret (via preferences)
  • Scrobble threshold setting
  • Debug logging preference

Installation Verification Checklist

After installation, verify everything is working:

  • Component appears in Preferences → Components
  • "Last.fm Scrobbler" appears in Preferences → Tools
  • API credentials are entered
  • Authentication shows "Authenticated as: username"
  • Playing a track past 50% adds it to the queue
  • Debug logging shows console messages (if enabled)
  • Track appears on Last.fm within 1-2 minutes
  • Offline queue file is created: ~/Library/foobar2000-v2/lastfm_scrobble_queue.json

Next Steps

Getting Help

If you encounter issues during installation:

  1. Check the Troubleshooting Guide
  2. Review the FAQ
  3. Open an issue on GitHub

Clone this wiki locally