spotify-history

What This Skill Does

The spotify-history skill acts as a bridge between the OpenClaw agent and your personal Spotify account. By utilizing the Spotify Web API, this skill allows the agent to audit your listening habits, retrieve your favorite artists and tracks over specific time horizons, and generate intelligent music recommendations based on your unique taste. It abstracts the complexity of OAuth authentication and API endpoint management, providing a clean CLI interface for both human users and AI agents to execute data-driven music insights.

Installation

To begin, ensure you have the OpenClaw environment ready. Install the skill using the command: clawhub install openclaw/skills/skills/braydoncoyer/spotify-history. After installation, run the setup wizard via bash skills/spotify-history/scripts/setup.sh. This process requires you to register an application on the Spotify Developer Dashboard to obtain your Client ID and Secret. You can store these credentials securely in a local JSON file or as environment variables. Once configured, execute python3 scripts/spotify-auth.py to initiate the OAuth flow. This creates a cached token in your home directory, allowing the agent to perform actions on your behalf securely without needing to re-authenticate daily.

Use Cases

• Music Discovery: Use the recommendation engine to find artists similar to your top performers that aren't already in your library.
• Retrospective Analysis: Generate reports on your listening habits over the last month, six months, or all time to see how your musical preferences have evolved.
• Content Curation: Provide the AI with your top tracks to have it build a themed playlist or analyze the common genres you gravitate toward during certain times of the day.
• Metadata Retrieval: Fetch granular details about current playback or historical sessions for use in other data processing workflows.

Example Prompts

1. "What are my top 5 artists from the last 6 months, and can you tell me what genres they fall into?"
2. "I'm tired of my current rotation; based on my listening history, recommend me some new music that fits a chill, ambient vibe."
3. "Show me what I was listening to most recently and give me a summary of my current musical mood."

Tips & Limitations

• Time Horizons: Always specify the time range (short_term, medium_term, long_term) to ensure the agent fetches the specific dataset you intend to analyze.
• API Limits: Be mindful that rapid, repetitive API requests might trigger Spotify's rate limiting. The agent is designed to handle standard queries gracefully.
• Security: Always maintain the security of your token.json file, as it grants full access to your Spotify account activity. Never share this file in public repositories.