Open the Door for Fortune

A command line game to guess songs, based on ffmpeg and iTunes Search API

Introduction

This project is inspired by a TV program called Kaimen Daji (Open the Door for Fortune) in China. In the program, the players are required to guess the names of random songs based on their intro melody. If they guess the correct answer, they receive some cash as rewards; otherwise, they fail.

This project will simulate its rules. The user will be asked to listen to slices of different songs and guess the song’s title, and if he/she guesses correctly, his/her score will increase by one.

There are two modes to choose:

• billboard mode can pick some songs from billboard’s hot-100 playlist randomly and let the user guess their titles.
• custom mode allows the user to input some artists’ names, analyze their popular songs in Apple Music, and let the user guess these songs’ titles in a random order.

The number of songs and whether to turn on “cheat mode” can also be modified. See “How to Use” for more information.

How to Use

Before running the program, please ensure the following dependencies are met:

1. Install Python Dependencies: Install the required Python packages by running: pip install -r requirements.txt

2. Install FFmpeg: Ensure that the FFmpeg multimedia framework is installed and accessible via your system’s command line (CLI). Download here.

This project does not have a GUI interface, so the user is required to run this project from the command line. Overall, the format is as follows.

python project.py [-n number] [-m mode] [-c]

The specific usage of these arguments is shown in the command line interface.

• -n or --number: customize the number of songs/questions, 10 by default.
• -m or --mode: specify the game mode, billboard by default.
• -c or --cheat: enable cheat mode.

Then, the user can follow the instructions on the command line.

Functions

project.py

• get_artistId(artist_name) can search an artist’s name and return his/her artist ID in iTunes
• get_track_by_artistId(artist_id) can get an artist’s popular track (name and preview link) through his/her artist id in iTunes
• get_track_by_title(song_title) can get a track (name and preview link) directly by searching it with iTunes Search API
• download_preview_audio(preview_url, filename) downloads an audio file from url and saves it
• make_audio_clip(input_file, output_file) extracts a ten-second clip from the audio file (0-10s)
• file_renamer(filename) renames the file to fit the playsound package
• remove_file(filename) removes a specific file
• guess_music(term, mode="song", cheat=False) is the core function that handles guessing a song, with two modes, and optional cheat mode
• scorer(playlist, is_cheat=False, mode="song") sets a loop and calculates the final score
• billboard_mode(number, is_cheat=False) gets songs from billboard’s hot-100 playlist
• custom_artist_mode(number, is_cheat=False) gets custom songs from user-inputted artists
• parse_arguments() manages command line arguments
• print_hints() prints usage hints
• main() runs the main program logic

test_project.py

• Functions in test_project.py test functions in project.py by pytest, and some functions are not suitable for testing.

Packages

All Packages: requirements

• argparse is a standard Python library used to write user-friendly command-line interfaces by easily handling and parsing arguments passed from the shell.
• requests is a simple, yet elegant HTTP library for Python, used to make API calls to iTunes and other services.
• ffmpeg-python is a Python wrapper for FFmpeg, used for audio processing to extract 10-second clips from audio files for the game.
• playsound is a simple Python module for playing sounds, used to play the song clips during gameplay.
• billboard is a Python API for the Billboard Hot 100 charts, used to retrieve current popular songs for the billboard game mode.
• pytest is a framework for easily writing simple and scalable tests for Python projects, used for unit testing the functions in test_project.py.

APIs

• iTunes Search API is a web service that allows developers to search Apple’s iTunes service for content like music, movies, artists, apps, and books, returning structured data in JSON format.

Software

• The user is required to install ffmpeg to use the audio splitter function.