hitster-card-generator

Hitster Card Creator

This Python project allows you to create printable cards and tokens for a game similar to the music guessing game Hitster. The generated PDF contains double-sided cards and tokens that can be printed, cut out, and used for gameplay.

If anything is unclear, please feel free to open an issue or contact me directly. I will do my best to help you out!

Features

Generate a PDF with cards based on data from a CSV file.
Cards can represent various types of content, such as songs, videos, articles, or paintings. Don’t limit yourself to just music! I made this project to create a Hitster-like game with some music, but also a lot of photos which one had to put in the right order.
Customizable card and page configurations, including colors and sizes.
Includes printable tokens for gameplay.

Example

If you have a CSV file with the following content:

Type	URL	Top	Bottom	Center
song	{long url}	Rick Astley	Never Gonna Give You Up	1987
song	{long url}	Keane	Bedshaped	2004
song	{long url}	Fox Stevenson	Curtain Call	2025
song	{long url}	Stephen	Crossfire	2015
song	{long url}	ODESZA	The Last Goodbye	2022
video	{long url}	bill wurtz	history of the entire world, i guess	2017
video	{long url}	Hank Green	Is it Better Not to Know?	2021
article	{long url}	Some text	Other text	2023
article	{long url}	Top	Bottom	1523
article	{long url}	Text here	Text there	1987
article	{long url}	To be	Not to be	OR
article	{long url}	Some text	Other text	2023

It will generate a PDF with cards like the following:

Note that the QR code on the top right corner of the page on the right corresponds to the card in the top left corner of the page on the left. This is because the cards are to be printed double-sided, and this way the QR codes will be aligned correctly.

Getting Started

If you are not familiar with Python or Git, you might want to check out this Google Colab notebook that provides a step-by-step guide to generating your own cards and tokens. The notebook includes instructions on how to upload your CSV file and run the code without needing to install anything on your local machine.

If you prefer to run the code locally, follow the instructions below.

Prerequisites

To use this project, you need:

Python 3.10 or higher installed on your system.
Basic knowledge of running Python scripts (no prior experience with Git or Python is required).

Installation

Download or clone this repository to your computer.
Open a terminal or command prompt and navigate to the project folder.
Create a virtual environment (optional but recommended):
```
python -m venv env
```
Activate the virtual environment (skip this step if you didn’t create one):
- On Windows:
```
.\env\Scripts\Activate.ps1
```
- On macOS/Linux:
```
source env/bin/activate
```
Install the required dependencies:
```
pip install -r requirements.txt
```

Usage

Prepare Your Data
- Place your data in a CSV file inside the data folder.
- The CSV file should follow the format of the provided example file data/data.csv:
```
type;url;top;bottom;center
song;https://example.com;Artist Name;Song Title;Year
video;https://example.com;Creator Name;Video Title;Year
article;https://example.com;Headline;Subheadline;Year
painting;https://example.com;Artist Name;Painting Title;Year
```
- The type column determines the type of card (e.g., song, video, article, painting).
- The url column contains the URL for the QR code. This can be any valid URL, such as a Spotify link, YouTube link, or a webpage link. For example, I used Google Drive links to images that I had uploaded to my Google Drive. Please ensure that the links are publicly accessible and long-lived, so that your cards will work for a long time.
- The top, bottom, and center columns contain the text that will be displayed on the front side of the card. The top and bottom columns are used for the top and bottom text, while the center column is used for the center text (typically a year). You can use any text you like, but make sure to keep it short enough to fit on the card.
Customize Configuration
- Open the src/config.py file to adjust settings such as:
  - Page and card sizes.
  - Colors for the front and back sides of the cards. The front side can be customized based on the type of card. Colors are given in RGB format (0-255).
- Note: Not all sizes are possible to ensure proper alignment for double-sided printing.
Generate the PDF
- Run the script to create the PDF:
```
python src/pdf.py
```
- The generated PDF will be saved in the outputs folder as output.pdf.
Print the Cards and Tokens
- Use thick paper (e.g., 300 grams) for printing.
- Print the PDF double-sided to ensure proper alignment of the card fronts and backs.
- Cut out the cards and tokens for gameplay.

Additional Information

The back sides of all cards are identical to prevent players from identifying the card type before flipping it.
Tokens are included in the PDF and are made using the assets/token.png image.

Example Token

Contributing

Feel free to fork this repository and make improvements. Pull requests are welcome!

License

This project is licensed under the MIT License. See the LICENSE file for details.

Enjoy creating your own custom cards and tokens for a fun and engaging game experience!