{Fork of} Hitster Card Generator

This is a fork of the awesome Hitster repo by fjlein. This fork was create to change the way you get a list of spotify songs. You can create a Hitster game with your all time favorite spotify song from the data spotify collects about you. Simple request your data from spotify, select how many of your most listened songs you want to use and you can start!

Get Spotify extended streaming history

Use an existing guide to request you extended streaming history. This can can take some days or weeks. Save the data as soon as you get them. Spotify will remove the download after 4 weeks and you have to make a new request.

Additional config for this fork

Set the path to your jsons folder in the environment.

export  CLIENT_ID="..."
export  CLIENT_SECRET="..."
export  SPOTIFY_JSONS="path/to/spotify/streaming/history"
export  SPOTIFY_HISTORY_MAX="150" # default is 150

SPOTIFY_JSONS: Folder with jsons, or a json file most likely called Streaming_History_Audio_20XX-20XY_X.json SPOTIFY_HISTORY_MAX: Number of cards to generate

If SPOTIFY_JSONS is present in the env, we use it. Else we try to download a playlist with the PLAYLIST_ID env var.

Hitster Card Generator

This project generates printable Hitster cards from a Spotify playlist. It retrieves song information from Spotify, generates QR codes linking to the songs, and creates a duplex printable PDF with cards using Typst.

If you find this DIY Hitster project useful, consider giving it a star :) !

Page Front	Page Back

✨ Features

• Spotify Integration: Fetches song details directly from a Spotify playlist.
• QR Code Generation: Creates QR codes for each song, linking to its Spotify URL.
• Printable Cards: Generates a PDF with formatted cards, ready for printing.
• Configurable Layout: Allows customization of card size and page layout.

⚙️ Prerequisites

• Python ^3.12
• Poetry (for dependency management)
• Spotify Developer Account (to obtain client credentials)

🛠️ Setup

1. Clone the repository:
2. Install dependencies using Poetry:

   poetry install

3. Set up Spotify API credentials:
   • Create a Spotify Developer account and create an app to get your CLIENT_ID and CLIENT_SECRET.
   • Set the following environment variables:

     export CLIENT_ID="your_client_id"
     export CLIENT_SECRET="your_client_secret"
     export PLAYLIST_ID="your_playlist_id"
     export SPOTIFY_JSONS="path/to/spotify/streaming/history"
     export SPOTIFY_HISTORY_MAX="150"

▶️ Usage

1. Run the main.py script:

   poetry run python main.py

2. Print the hitster.pdf file:
   • Open the hitster.pdf file and duplex print it.
   • Cut along the provided markings to create the Hitster cards.

🎲 How to Play

1. Open your camera app and scan the QR code.
2. Spotify will launch and the song will start playing.
3. After scanning, quickly look away to keep things fair!
   • Since the song title and artist will be visible, the person scanning should not be the one guessing.
   • Since the release year might be visible on the cover, the person scanning should scan and look away.
4. Have fun!

🎨 Customization

• Card Layout: Modify the hitster.typ file to customize the card layout, size, and appearance.
• Spotify Playlist: Change the PLAYLIST_ID environment variable to use a different Spotify playlist.
• Card Dimensions: Change the card_size, rows, and cols variables in hitster.typ to adjust the card dimensions and page layout.
• Marking Size: Change the marking_padding to adjust the space for cutting.