shfl

A deterministic shuffle tool for generating reproducible index mappings and shuffling Spotify playlists.

Features

• Deterministic shuffling: Given the same key/seed and size, always produces the same shuffle order
• Index mapping: Generate shuffled index arrays for any size
• Spotify integration: Shuffle Spotify playlists with a new deterministic order
• Deduplication: Optionally remove duplicate items when shuffling playlists
• Dry-run mode: Preview shuffle results without creating a new playlist

Installation

cargo install --path .

Or build from source:

cargo build --release

Usage

Index Mapping (ind-map)

Generate a shuffled index mapping for a given size and key:

# Basic usage
shfl ind-map <SIZE> <SHUFFLE_KEY>

# Example: Generate shuffled indices for 10 items
shfl ind-map 10 my-secret-key
# Output: [3, 7, 1, 9, 0, 5, 2, 8, 4, 6]

# With timing information
shfl ind-map 1000 my-key -t

Arguments:

• SIZE - Number of indices to shuffle (0 to N-1)
• SHUFFLE_KEY - Key for deterministic shuffle (same key = same result)
• -t - Show execution time

Spotify Playlist Shuffle (spotify)

Shuffle a Spotify playlist into a new playlist with deterministic ordering:

shfl spotify <ACCESS_TOKEN> <SOURCE_NAME> <DEST_NAME> <SEED> [OPTIONS]

Arguments:

• ACCESS_TOKEN - Spotify OAuth access token
• SOURCE_NAME - Name of the source playlist to shuffle
• DEST_NAME - Name for the new shuffled playlist
• SEED - Seed for deterministic shuffle

Options:

• -d - Remove duplicate tracks
• -n, --dry-run - Preview what would happen without creating the playlist

Example:

# Shuffle a playlist
shfl spotify "your-token" "My Playlist" "My Playlist (Shuffled)" "2024-shuffle"

# Shuffle with deduplication
shfl spotify "your-token" "My Playlist" "My Playlist (Shuffled)" "2024-shuffle" -d

# Preview shuffle without creating playlist
shfl spotify "your-token" "My Playlist" "My Playlist (Shuffled)" "2024-shuffle" -n

Note: Only tracks are supported; episodes in playlists will be skipped with a warning. The tool uses Spotify's /items API endpoints.

Determinism Guarantees

The shuffle algorithm provides the following guarantees:

1. Reproducibility: The same shuffle_key/seed and size will always produce the identical shuffle order, regardless of when or where the program is run.

2. Algorithm: Uses ChaCha8 CSPRNG seeded with a 64-bit hash (xxHash) of the shuffle key.

3. Stability: The shuffle is a valid permutation - every index from 0 to size-1 appears exactly once.

4. Cross-platform: Results are consistent across different operating systems and architectures.

How It Works

shuffle_key → xxHash64 → 64-bit seed → ChaCha8 RNG → Fisher-Yates shuffle

1. The shuffle key is hashed using xxHash64 to produce a 64-bit seed
2. The seed initializes a ChaCha8 random number generator
3. A Fisher-Yates shuffle is performed on the index array
4. The result is a deterministic permutation of indices

Getting a Spotify Access Token

To use the Spotify shuffle feature, you need an OAuth access token with the following scopes:

• playlist-read-private
• playlist-modify-private
• playlist-modify-public

You can obtain a token through:

1. Spotify Developer Dashboard
2. OAuth authorization flow
3. Third-party tools like spotify-token-gen

Examples

Deterministic Playlist Ordering

Use the same seed to recreate the exact same shuffle:

# First run
shfl spotify "$TOKEN" "Favorites" "Favorites Jan 2024" "january-2024"

# Running again with same seed produces identical order
shfl spotify "$TOKEN" "Favorites" "Favorites Jan 2024 Copy" "january-2024"

Monthly Shuffled Playlists

Create consistently shuffled playlists using date-based seeds:

shfl spotify "$TOKEN" "Workout Mix" "Workout Jan" "2024-01"
shfl spotify "$TOKEN" "Workout Mix" "Workout Feb" "2024-02"

License

MIT