Shredster is a program for creating custom Hitster song cards. It is a fork of the SongSeeker Card Generator, a Python script designed to create visual cards based on song data. See the SongSeeker project for the original.
Shredster adds the ability to pull data from Spotify for ease of creating shredster decks to play with. It also adds a way to play without printing cards, although you will still need something physical to track your timelines, such as sticky notes or index cards.
- Generate cards for songs with a QR code on one side and the song info on the other.
- PDF output for double sided printing.
- Input data in CSV format.
- Scrape data from Spotify songs and/or playlists.
- Play without printing cards via
game.py.
python generatePlayCardsFromSpotify.py https://open.spotify.com/playlist/6KQrlKHRIkn42J02uXAFdG data/example.csv
python game.py data/example.csvpython generatePlayCardsFromSpotify.py https://open.spotify.com/playlist/6KQrlKHRIkn42J02uXAFdG pdfs/example.pdfpython generatePlayCardsFromCSV.py data/example-youtube-songs.csv pdfs/example.pdfFull usage documentation can be found below.
Make sure you have Python installed on your system. The script is tested with Python 3.11 and above. You can download and install Python from here.
Clone the repository to your local machine using the following command:
git clone https://github.com/rgrwkmn/shredsterNavigate to the cloned directory:
cd shredsterCreate a python virtualenv:
python -m venv ./venvActivate the virtualenv
source venv/bin/activateInstall the required Python packages:
pip install -r requirements.txtpython generatePlayCardsFromCsv.py <input_csv_path> <output_pdf_path>python generatePlayCardsFromCsv.py data/example-youtube-songs.csv example.pdfYou can also add an icon to the card by using the --icon flag:
# Add icon from a url
python generatePlayCardsFromCsv.py data/example-youtube-songs.csv example.pdf --icon https://github.com/andygruber/songseeker/blob/main/icons/icon-96x96.png?raw=true
# Add icon from a local file
python generatePlayCardsFromCsv.py data/example-youtube-songs.csv example.pdf --icon ../songseeker/icons/icon-96x96.pngYou can set the pagesize to A4 or letter based on your printer page size. The default is letter.
python generatePlayCardsFromCsv.py data/example-youtube-songs.csv example.pdf --pagesize=A4The input CSV file should have the following format:
Title: The title of the song.Artist: The artist of the song.Year: The release year of the song.URL: The YouTube URL of the song. If the song does not start at the beginning of the video, you may also add the starting time in seconds to the end of the link, like?t=16.
Make sure your CSV file includes headers and the data is separated by commas.
An example can be found in data/example-youtube-songs.csv.
First, you will need to have a Spotify Web API client ID and secret for API access by creating a Spotify App. Copy the spotifyauth.example.json file to spotifyauth.json and paste your credentials in there.
There are a few ways to use the generatePlayCardsFromSpotify.py script. When generating a PDF, the --icon and --pagesize options are the same as generatePlayCardsFromCsv.py detailed above.
Simply provide the URL of a public spotify playlist
python generatePlayCardsFromSpotify.py https://open.spotify.com/playlist/6KQrlKHRIkn42J02uXAFdG pdfs/spotify.pdfPaste as many song and playlist URLs as you like on separate lines into a .txt file and load that. Handy if you want to put together a bunch of songs and playlists. See data/example-spotify.txt for an example.
python generatePlayCardsFromSpotify.py data/example-spotify.txt pdfs/spotify.pdfGive a directory path and it will load all .txt files in that directory. Handy if you want to create a game from multiple contributors and attribute the source of each song.
python generatePlayCardsFromSpotify.py data pdfs/spotify.pdfIf the output path ends in .csv it will save a CSV file of the song data instead of creating a PDF. Use this if you want to save the data locally to play with game.py. You can also open the CSV to fine tune the data if you find that anything is inaccurate.
python generatePlayCardsFromSpotify.py data/example-spotify.txt data/spotify.csvSince the Spotify functionality automatically pulls the song Artists, Title, and Year, it's important to select the right version of a Song to get accurate information.
The data for the song's release year comes from its album release year. So if you choose a song from a compilation such as a Best Of album, the release year will not be correct. Remasters and Reissues have had the original release year in my experience, so those should be OK to use.
If you can't find the song you want in its original version on Spotify, you can always save from Spotify to CSV and edit the info from there before generating a PDF or playing with game.py.
See the Official Hitster Rules for overall gameplay rules.
Print a test page with just a few songs on it first to make sure you have the PDF page size and double sided print settings correct! When you are sure the print is coming out correctly, print all of your cards and cut them out.
Playing with printed cards is the same as playing regular Hitster, except instead of scanning the cards with the Hitster app, you will scan them with your phone camera QR code scanner. Depending on how the songs are being played, the person doing the scanning may need to quickly put their phone down so they don't see the song info.
Instead of printing, you can run game.py from the command line and it will act as a virtual deck. Simply create a CSV or save your Spotify playlist or songs to a CSV.
python game.py data/example-youtube-songs.csvIt will show you how many cards are in the deck, how many are in the "discard pile", and the QR code side of the current card.
Deck: 58 , Discard: 0
█▀▀▀▀▀█ █▄██ ██ ▄▄▀▄▄█▄ ▄ █▀▀▀▀▀█
█ ███ █ ▀ ▀█▀▀█ █ ▄▄█▀ █▄ █ ███ █
█ ▀▀▀ █ ▀ ▀▀██ ██▀█▀▄███▄ █ ▀▀▀ █
▀▀▀▀▀▀▀ ▀▄▀ █▄▀▄█ ▀ █ █ █ ▀▀▀▀▀▀▀
▀ ██▀▀▀█▄ ▀▀▄▄▄▀█▄▄▄▄ ▄█▀ █▄█▀█
█ ▀██▀▀▀▀█▄▀██ ▀█ ▄ ▄▀▀█▀▄▀▀█▀█
▄▀▄▄▀▀▀▀█ █▄ █▄▀ █▄▄▀▀▄ ▀ ▀
█▀▀▄█▄▀▄▀▀█▄ ▄▄▀▄▀ █ ▀█▄▀▄▀ ▄█▄ ▄
▀██▀▀▀▀ ▄▄▀█ ▀ █ ▄▄▄▄ █▀▀▀█▀█▀▄▄▄
▀ ▄▄▀▄▀▄▄█▄ ▀█▀▀▀▀▀▀ ▀ ▄█▀▄██▀█
██▄▀ ▄▀▀ ▄ █▄█ ▀▀▄▀▀ ▄▄▄ █▄█ ▀
█ ▀ ▄█▀█▀█ ▀▄ ▄ █ ▀▀ █▄▀█ ▄█▀
▀▀ ▀▀▀▀▄▀ ▀▀█ ▄▄▄█▀▀▄▄▀█▀▀▀█ █ ▀
█▀▀▀▀▀█ █▀▄▀▄▄ ▀▀█▄▀█ ██ ▀ █▄██
█ ███ █ █▀▄ ▄▀█▀▄█ ████▀█▀▄▄█▄
█ ▀▀▀ █ ▄▀█▀ ▀▀ ▀ ▀ █▀ ▄██▄▄██
▀▀▀▀▀▀▀ ▀▀ ▀▀▀▀ ▀ ▀ ▀▀ ▀▀▀
Use the right arrow to reveal the song info side of the card.
Deck: 58 , Discard: 0
Title: American Canon
Artist: Wolfsmyth
Year: 2018
Source: spotify
Use the right arrow again to show the QR code of the next card.
Deck: 57 , Discard: 1
█▀▀▀▀▀█ █▀▄ ▄ ▄ █▀▀▀█ ██ █▀▀▀▀▀█
█ ███ █ ▄███ ▀▀█▀ ▄▄▀ ███ █ ███ █
█ ▀▀▀ █ ▀ █ ▀ ▄██ █▄▄▄▀▀ █ ▀▀▀ █
▀▀▀▀▀▀▀ █▄▀▄█ ▀▄█▄█▄▀ █ ▀ ▀▀▀▀▀▀▀
▀ █▀ ▀▀▀ ▀▄ ▄ ▀████ ▀▄▄▄ █▄ █▄██
▄█▀▄▀▀▀█▀▀ █ ▀ █▄▀▄ ▀▀█▄█▀█▀█ ▄▀
▀█▀ █▀ ▄ █▀▄ █▀▀ █ ▄▀█▄ ▄▀█▄█
▄▀ █▀▄▀▀ ▄▀█ ▄ ▄ ▀▀█▄▄▀ ▀▄█▄ ▄▄
▀█ ██▀█▄█▀▀██ ▄ ▀ ▄▀██▄██ ██ ▄
▀ ▀ ▀▄▀▀ ▄ █ ▄█▄ ▄▄▄█▀█ ▀
▄▀ █ ▀▀▄ ▄█ ▄▀▄█▄ ██▀█ ▀█▄▀ ▀█ ▄
▄ █▄▀▀█ ▄ ▀█▄ █ ▀█▄█▀▀█▀▀▄███▀▀▀
▀ ▀▀█▀▀▄█ ▀▄█▀▀▄ ███▀▀▀█▄▀█
█▀▀▀▀▀█ █▀ ▀██ ▄███▀▀▄ ██ ▀ █▄▄█▄
█ ███ █ ▄▀▄ ▄ ██▀▀ █▀▀▀▀█▀▄█▀▄
█ ▀▀▀ █ ▀▄ ▀▄█ ▀▀█▄ █▀▀▄█▀▀█▄▀▀ ▄
▀▀▀▀▀▀▀ ▀ ▀ ▀▀ ▀▀▀ ▀ ▀ ▀ ▀
You can continue navigating forward through the deck with the right arrow, or go back with the left arrow.
You will need to reveal one card per player to start the game. Players should write down their song info on sticky notes, index cards, etc. in order to build their timelines.
Contributions are welcome.
This project is licensed under the AGPL-3.0 license - see the LICENSE file for details.