Skip to content

Configuration Files

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

Configuration Files

This page documents all configuration files used by foo_mac_scrobble, their locations, formats, and purposes.

Overview

The component uses several configuration files:

File Location Format Purpose
Session ~/Library/foobar2000-v2/lastfm_session.json JSON Last.fm credentials
Queue ~/Library/foobar2000-v2/lastfm_scrobble_queue.json JSON Offline scrobbles
Preferences ~/Library/foobar2000-v2/config.sqlite Binary foobar2000 config

Session File

Location

~/Library/foobar2000-v2/lastfm_session.json

Purpose

Stores Last.fm authentication credentials after successful login.

Format

{
  "session_key": "d580d57f32848420e4155f4r4d5e6d8e",
  "username": "lastfm_username"
}

Fields

Field Type Description
session_key String Last.fm API session key (32 hex chars)
username String Last.fm username for display

Lifecycle

  • Created: After successful authentication
  • Read: On component startup
  • Updated: Only during re-authentication
  • Deleted: When clearing session or re-authenticating

Security Considerations

⚠️ Security Note: This file contains your Last.fm session key, which grants access to your Last.fm account.

Recommendations:

  • Keep file permissions restricted (readable only by your user)
  • Don't share this file publicly
  • Don't commit to version control
  • If compromised, revoke access on Last.fm and re-authenticate

File Permissions

By default, the file has:

-rw-r--r--  1 username  staff  123 Nov 17 12:34 lastfm_session.json

Manual Editing

You can manually edit this file, but:

  1. Stop foobar2000 first
  2. Use valid JSON syntax
  3. Ensure session key is valid (32 hex characters)
  4. Restart foobar2000 after editing

Example:

# Edit the session file
nano ~/Library/foobar2000-v2/lastfm_session.json

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

Troubleshooting

File doesn't exist:

  • You haven't authenticated yet
  • Session was cleared
  • File was manually deleted

Invalid session key:

  • Delete file and re-authenticate
  • Check for JSON syntax errors

Queue File

Location

~/Library/foobar2000-v2/lastfm_scrobble_queue.json

Purpose

Stores tracks waiting to be scrobbled (offline queue).

Format

[
  {
    "artist": "Queen",
    "track": "Bohemian Rhapsody",
    "album": "A Night at the Opera",
    "album_artist": "Queen",
    "track_number": "11",
    "mbid": "",
    "timestamp": 1700000000
  },
  {
    "artist": "Pink Floyd",
    "track": "Comfortably Numb",
    "album": "The Wall",
    "album_artist": "Pink Floyd",
    "track_number": "6",
    "mbid": "",
    "timestamp": 1700000120
  }
]

Fields

Field Type Required Description
artist String Yes Artist name
track String Yes Track title
album String No Album name
album_artist String No Album artist (if different from track artist)
track_number String No Track number on album
mbid String No MusicBrainz ID (usually empty)
timestamp Integer Yes Unix timestamp (seconds since epoch)

Lifecycle

  • Created: When first track is queued
  • Read: On component startup
  • Updated: When tracks are added or removed
  • Persisted: After every queue change
  • Deleted: When manually clearing queue

Queue Processing

The background worker processes the queue:

  1. Every 30 seconds (if authenticated and online)
  2. Batches up to 50 tracks per API request
  3. Removes successfully submitted tracks
  4. Retains failed tracks for next attempt

Size Considerations

Queue Size File Size Processing Time
10 tracks ~2 KB < 1 second
100 tracks ~20 KB 2-3 seconds
1,000 tracks ~200 KB 20-30 seconds
10,000 tracks ~2 MB 3-5 minutes

Note: Large queues (1000+) may indicate network issues.

Manual Inspection

View the queue:

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

Pretty-print with jq:

brew install jq
cat ~/Library/foobar2000-v2/lastfm_scrobble_queue.json | jq

Count pending tracks:

cat ~/Library/foobar2000-v2/lastfm_scrobble_queue.json | jq 'length'

Manual Editing

You can edit the queue file:

  1. Stop foobar2000
  2. Edit with valid JSON syntax
  3. Ensure all required fields are present
  4. Use valid Unix timestamps
  5. Restart foobar2000

Example: Add a track manually

[
  {
    "artist": "The Beatles",
    "track": "Here Comes the Sun",
    "album": "Abbey Road",
    "album_artist": "The Beatles",
    "track_number": "7",
    "mbid": "",
    "timestamp": 1731844800
  }
]

Clearing the Queue

Option 1: Delete the file

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

Option 2: Empty the array

echo '[]' > ~/Library/foobar2000-v2/lastfm_scrobble_queue.json

Then restart foobar2000.

Troubleshooting

Queue not processing:

  • Check authentication status
  • Verify internet connection
  • Enable debug logging and check Console

Queue file corrupted:

Last.fm: Failed to parse queue file: [JSON parse error]

Solution: Delete and let component recreate:

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

Queue growing indefinitely:

  • Network issues preventing submission
  • Invalid session key
  • Last.fm API unavailable

Check Console logs for specific errors.

foobar2000 Preferences

Location

~/Library/foobar2000-v2/config.sqlite

Purpose

Stores foobar2000's configuration database, including component settings.

Format

sqlite

The component's preferences are stored using foobar2000's cfg_var system:

cfg_string cfg_api_key(guid_cfg_api_key, "");
cfg_string cfg_api_secret(guid_cfg_api_secret, "");
cfg_int cfg_scrobble_threshold(guid_cfg_threshold, 50);
cfg_bool cfg_debug_logging(guid_cfg_debug, false);

Stored Values

Setting Type Default Description
API Key String Empty Last.fm API Key
API Secret String Empty Last.fm API Secret
Scrobble Threshold Integer 50 Percentage of track (1-100)
Debug Logging Boolean false Enable console logging

Persistence

  • Automatic: Changes save immediately
  • Thread-safe: SDK handles synchronization
  • Crash-safe: Atomic writes via SDK

Resetting Preferences

Option 1: Via foobar2000

  1. Preferences → Tools → Last.fm Scrobbler
  2. Clear API Key and Secret
  3. Set threshold to default (50%)
  4. Disable debug logging

Option 2: Reset entire foobar2000 config

⚠️ Warning: This resets ALL foobar2000 preferences, not just the component.

rm -rf ~/Library/foobar2000-v2/config.sqlite

Then restart foobar2000.

Backup & Restore

Backup preferences:

cp -r ~/Library/foobar2000-v2/config.sqlite ~/config.sqlite.backup

Restore preferences:

rm -f ~/Library/foobar2000-v2/config.sqlite
cp ~/config.sqlite.backup ~/Library/foobar2000-v2/config.sqlite

Component Info

Location

~/Library/foobar2000-v2/user-components/foo_mac_scrobble/foo_mac_scrobble.component/Contents/Info.plist

Purpose

macOS bundle metadata.

Format

XML Property List:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>CFBundleDevelopmentRegion</key>
    <string>en</string>
    <key>CFBundleExecutable</key>
    <string>foo_mac_scrobble</string>
    <key>CFBundleIdentifier</key>
    <string>com.foo.mac.scrobble</string>
    <key>CFBundleInfoDictionaryVersion</key>
    <string>6.0</string>
    <key>CFBundleName</key>
    <string>foo_mac_scrobble</string>
    <key>CFBundlePackageType</key>
    <string>BNDL</string>
    <key>CFBundleShortVersionString</key>
    <string>0.1.2</string>
    <key>CFBundleVersion</key>
    <string>1</string>
</dict>
</plist>

Key Fields

Key Value Description
CFBundleIdentifier com.foo.mac.scrobble Unique bundle ID
CFBundleShortVersionString 0.1.2 User-facing version
CFBundleVersion 1 Build number
CFBundleExecutable foo_mac_scrobble Binary name

Not user-editable — managed by Xcode build system.

File Paths Reference

Quick reference for all configuration files:

# Session credentials
~/Library/foobar2000-v2/lastfm_session.json

# Offline queue
~/Library/foobar2000-v2/lastfm_scrobble_queue.json

# foobar2000 preferences (binary)
~/Library/foobar2000-v2/config.sqlite

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

# Component binary
~/Library/foobar2000-v2/user-components/foo_mac_scrobble/foo_mac_scrobble.component/Contents/MacOS/foo_mac_scrobble

# Component metadata
~/Library/foobar2000-v2/user-components/foo_mac_scrobble/foo_mac_scrobble.component/Contents/Info.plist

Backup Strategy

Essential Files to Backup

# Create backup directory
mkdir -p ~/foobar2000-backup/

# Backup session
cp ~/Library/foobar2000-v2/lastfm_session.json ~/foobar2000-backup/

# Backup queue (optional, will rebuild)
cp ~/Library/foobar2000-v2/lastfm_scrobble_queue.json ~/foobar2000-backup/

# Backup preferences (includes all foobar2000 settings)
cp -r ~/Library/foobar2000-v2/config.sqlite ~/foobar2000-backup/

Restore from Backup

# Restore session
cp ~/foobar2000-backup/lastfm_session.json ~/Library/foobar2000-v2/

# Restore queue (optional)
cp ~/foobar2000-backup/lastfm_scrobble_queue.json ~/Library/foobar2000-v2/

# Restore preferences
rm -f ~/Library/foobar2000-v2/config.sqlite
cp ~/foobar2000-backup/config.sqlite ~/Library/foobar2000-v2/config.sqlite

# Restart foobar2000

Migration Between Machines

To move your setup to a new Mac:

  1. On old Mac:

    # Export component and config
tar -czf foobar-lastfm-backup.tar.gz \
  ~/Library/foobar2000-v2/lastfm_session.json \
  ~/Library/foobar2000-v2/lastfm_scrobble_queue.json \
  ~/Library/foobar2000-v2/config.sqlite

  2. Transfer file to new Mac (via USB, AirDrop, cloud, etc.)

  3. On new Mac:

    # Install foobar2000
# Install foo_mac_scrobble component

# Extract backup
tar -xzf foobar-lastfm-backup.tar.gz -C ~/

# Start foobar2000

Security Best Practices

File Permissions

Ensure proper permissions:

# Session (sensitive)
chmod 600 ~/Library/foobar2000-v2/lastfm_session.json

# Queue (less sensitive)
chmod 644 ~/Library/foobar2000-v2/lastfm_scrobble_queue.json

# Config file
chmod 700 ~/Library/foobar2000-v2/config.sqlite

Sensitive Data

Never:

  • Commit session file to version control
  • Share session file publicly
  • Post session key in issues or forums
  • Include in screenshots

If compromised:

  1. Delete lastfm_session.json
  2. Visit https://www.last.fm/settings/applications
  3. Revoke access for the component
  4. Re-authenticate in foobar2000

Environment Variables

The component doesn't use environment variables, but you can set these for convenience:

# In ~/.zshrc or ~/.bash_profile
export FOOBAR_CONFIG="$HOME/Library/foobar2000-v2"
export LASTFM_SESSION="$FOOBAR_CONFIG/lastfm_session.json"
export LASTFM_QUEUE="$FOOBAR_CONFIG/lastfm_scrobble_queue.json"

# Usage:
cat $LASTFM_SESSION
cat $LASTFM_QUEUE

Related Documentation

Questions about configuration files? Open an issue on GitHub.

Clone this wiki locally