Usage

🎮 Usage Guide

This guide covers the various ways to use Simkl Scrobbler.

📋 Basic Commands

# Initial setup (only needed once)
simkl-mps init

# Start tracking in foreground mode
simkl-mps start

# Launch in system tray
simkl-mps tray

# Run as a background service
simkl-mps service

# Check service status
simkl-mps service-status

# Process pending offline items
simkl-mps process-backlog

# Show all available commands
simkl-mps --help

🚀 Run Modes

🔄 Background Mode

simkl-mps start

Runs silently in the background. This is the standard way to run the application for regular usage.

🖥️ System Tray Mode

simkl-mps tray

Runs as a system tray application, allowing you to:

• Start/stop monitoring
• Process the backlog
• View logs
• Exit the application

🔄 Service Mode

simkl-mps service

Runs as a background service with no UI. Useful for headless operation or when you want the application to run independently of user sessions.

⚙️ System Service (Auto-start)

# Install as a system service
simkl-mps install-service

# Uninstall the service
simkl-mps uninstall-service

# Check service status
simkl-mps service-status

This installs the application to run automatically when your system starts, with platform-specific implementations:

• Windows: Registry startup entry
• macOS: LaunchAgent
• Linux: systemd user service

💻 Command-Line Arguments

# Show detailed help
simkl-mps --help

# Show application version
simkl-mps --version

# Run with debug logging
simkl-mps start --debug

# Use a specific config file
simkl-mps start --config /path/to/config.env

📁 Log Files

Check these files for troubleshooting:

# Main application log
[APP_DATA_DIR]/kavinthangavel/simkl-mps/media-player-scrobbler-for-simkl.log

# Detailed playback events
[APP_DATA_DIR]/kavinthangavel/simkl-mps/playback_log.jsonl

Where [APP_DATA_DIR] is platform-specific:

• Windows: %APPDATA%
• macOS: ~/Library/Application Support
• Linux: ~/.local/share

🔧 Environment Variables

You can set these environment variables to customize behavior:

Variable	Purpose	Default
SIMKL_CLIENT_ID	Custom API client ID	Built-in ID
SIMKL_ACCESS_TOKEN	Manual access token	Auto-generated
SIMKL_LOG_LEVEL	Logging verbosity (DEBUG, INFO, etc.)	INFO
SIMKL_POLL_INTERVAL	Window check frequency (seconds)	10
SIMKL_COMPLETION_THRESHOLD	% to mark as watched	80

🔍 Recommended Workflow

1. Run simkl-mps init to set up your Simkl account
2. Test with simkl-mps start to ensure detection works in background mode
3. For daily use, either:
   • Use simkl-mps tray for easy access to controls
   • Install as a service with simkl-mps install-service for automatic startup

📊 Operation Flow

The following diagram illustrates how the different run modes operate:

graph TD
    A[Simkl Scrobbler] --> B[Background Mode]
    A --> C[System Tray Mode]
    A --> D[Service Mode]
    A --> E[System Service]
    
    B -->|No UI| F[Standard Tracking]
    C -->|Tray Icon| G[Control Panel]
    D -->|No UI| H[Independent Tracking]
    E -->|Auto-start| I[Boot Tracking]
    
    F --> J[Simkl API]
    G --> J
    H --> J
    I --> J
    
    style A fill:#f9d5e5,stroke:#333,stroke-width:2px
    style J fill:#d5f5e3,stroke:#333,stroke-width:2px

Loading