Spoti - Spotify Jam Queue Shuffler

A lightweight command-line tool to shuffle tracks in your Spotify Jam queue directly from the terminal.

Features

• 🎵 Shuffle tracks in your Spotify Jam queue
• 🔐 Secure OAuth2 authentication with Spotify
• ⚡ Fast and efficient CLI interface
• 🔄 Multi-account support (switch accounts anytime)
• ✨ Beautiful spinner feedback during operations

Prerequisites

• Node.js 16+ (recommended: 18+)
• npm or yarn
• A Spotify account
• Spotify Developer Application credentials (see Setup)

Installation

Install the package globally via npm:

npm install -g spoti-shuffler

Or use it with npx:

npx spoti-shuffler login
npx spoti-shuffler shuffle

Setup

1. Create a Spotify Developer Application

1. Go to Spotify Developer Dashboard
2. Log in with your Spotify account (create one if needed)
3. Create a new application
4. Accept the terms and create the app
5. Copy your Client ID and Client Secret

2. Configure Environment Variables

Create a .env file in your home directory or working directory:

SPOTIFY_CLIENT_ID=your_client_id_here
SPOTIFY_CLIENT_SECRET=your_client_secret_here
SPOTIFY_REDIRECT_URI=http://localhost:8888/callback

Important Security Note: Never share your .env file or credentials publicly.

Usage

Authenticate with Spotify

Before shuffling, authenticate with your Spotify account:

spoti login
# or
spoti auth

Switch Accounts:

spoti login --relogin
# or
spoti login -r

Shuffle Your Jam Queue

Shuffle tracks in your current Jam:

spoti shuffle
# or
spoti s

Shuffle specific number of tracks:

spoti shuffle --tracks 10
# or
spoti s -n 10

Commands Reference

login (alias: auth)

Authenticate with Spotify.

Options:

• -r, --relogin — Switch accounts (logs out current account if already logged in)

Examples:

spoti login
spoti auth
spoti login --relogin
spoti login -r

shuffle (alias: s)

Shuffle tracks in the current Jam queue.

Options:

• -n, --tracks <number> — Number of user tracks to shuffle (default: 5)

Examples:

spoti shuffle
spoti s
spoti shuffle --tracks 20
spoti s -n 20

How It Works

1. Authentication — Uses OAuth2 flow to securely authenticate with Spotify
2. Token Management — Stores and refreshes tokens automatically
3. Queue Access — Accesses your current Spotify Jam queue
4. Shuffling — Randomly reorders specified tracks in your queue

Troubleshooting

"Failed to log in"

• Ensure your .env file has valid Spotify credentials
• Check that SPOTIFY_REDIRECT_URI matches your app's redirect URI in Spotify Dashboard
• Delete your saved tokens and try logging in again

"Queue shuffle failed"

• Make sure you're logged in: spoti login
• Ensure you have an active Spotify Jam with tracks
• Try increasing the --tracks value to match available tracks

Port Already in Use

If port 8888 is busy, update SPOTIFY_REDIRECT_URI in your .env and Spotify Dashboard to use a different port.

Development

To develop locally, clone the repository and follow the source installation:

git clone https://github.com/yourusername/jam-shuffler.git
cd jam-shuffler
npm install
npm run build
npm run dev -- login
npm run dev -- shuffle

Available Scripts:

• npm run dev — Run the app in development mode with tsx
• npm run build — Compile TypeScript to JavaScript
• npm start — Run the compiled application

Project Structure:

jam-shuffler/
├── src/
│   ├── index.ts          # Entry point
│   ├── app.ts            # CLI application setup
│   ├── config/           # Configuration files
│   └── services/         # Business logic services
├── dist/                 # Compiled JavaScript
├── package.json          # Dependencies and scripts
└── tsconfig.json         # TypeScript configuration

Dependencies

• commander — CLI argument parsing
• axios — HTTP client for API requests
• express — OAuth callback server
• dotenv — Environment variable management
• ora — Terminal spinner for visual feedback
• open — Open URLs in default browser

License

ISC

Author

Maenard

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

For issues and questions, please open an issue in the repository.