Storyboarder

Storyboarder is an assistant that helps in writing visual quizbowl sets by automating cumbersome parts of the process. Storyboarder can help create sets/packets that are hybrid written + visual (e.g. Untitled Film Set) or fully visual (e.g. Eyes That Do Not See). The primary purpose is to assist in production of film sets, but Storyboarder can be used for visual packets that draw from any combination of media (film, television, online videos, art, photography, literature, etc.).

The main component of Storyboarder is a script that automatically generates a set of hybrid packets by parsing a set of written questions and a CSV containing metadata about a set of visual questions.

Important

The hybrid packet generation is compatible with both Oligodendrocytes and MODAQ (which also uses YAPP). The pipeline to interface with MODAQ has been thoroughly tested for Untitled Film Set.

Contents

• Google Drive folder
  • Google Slides template for standardized, color-coded visual packets ¹
  • A visual answerline database template ² (which should be exported as a CSV once configured)
• Python scripts
  • storyboarder.py
    • The backend script that generates the visual answerline document and hybrid packets by parsing a properly-configured visual answerline database CSV
  • config.py
    • The front-facing script that configures the set metadata and how to perform the creation.

Requirements

• Python(3)
• A properly-configured visual answerline database CSV
• If hybrid is configured, a set of packets as Word documents that contain the questions for the written portion of a hybrid tournament

Outputs

• A roughly-formatted visual answerline document that contains both answerlines and slide-by-slide information for each visual question
• If hybrid is configured, a set of hybrid packets that contain any combination of written and visual questions, for convenient use by moderators using Oligodendrocytes or MODAQ

Usage

1. Install, e.g. using pip:
   • pandas
   • python-docx
   • haggis
   • tmdbv3api
2. Setup the visual answerline database using the template as an example.
   • Each visual question comprised of $n$ slides corresponds to $n$ rows.
   • Each row per question, including the first, must contain the other metadata about the source of the respective slide (Packet, Number, Source and Value).
   • The first row for each question is special in that it must also contain the necessary metadata about the question (Answerline and Answerline_Type ³).
   • Make sure to use the correct Answerline_Type based on the answerline. The following Answerline_Types are recognized by Storyboarder:
     • Film
     • Creator
     • Director
     • Figure
     • Crew
     • Location
     • Surname
     • Misc
   • Optional columns are Source_Type, Source_Year, and Creator.
     • Storyboarder automatically populates the information regarding film directors using the tmdbv3api utility to search TMDB.
     • To help the automatic detection, you may provide the film's release year in the Source_Year column for the corresponding row.
     • To override the automatic results for a given Source, you can explicitly assign its Creator in the corresponding cell.
     • The default Source_Type per source is assumed to be Film, so unless the Source is not a film, you may leave the corresponding cell empty.
     • To reference a music video, video game, or essay in a slide rather than a film for a given Source, change the Source_Type. Specifically for the Music Video type, add quotation marks around the Source value.
3. Configure the parameters in config.py and run config.py.
4. You should now have:
   • A roughly-formatted visual answerline document that contains both answerlines and slide-by-slide information for each visual question.
   • (If configured) a set of hybrid packets that contain both written and visual questions for convenient use by moderators using MODAQ or Oligodendrocytes.

Example

See the demo/untitled-film-set directory of this repository for a set of example packets generated using the database template and scripts for 2024 Untitled Film Set.

Notes

Warning

Make sure you close all Storyboarder-generated files (hybrid packets, visual answerlines spreadsheet) before running config.py, since python-docx cannot rewrite any files that are currently open and will hence throw an error.

Important

Storyboarder can handle fully-visual tournaments. Just configure hybrid = True and create a set of empty packet files in set_dir to act as the "written" files.

Warning

Storyboarder performs a first run of formatting on each answerline. However, once Storyboarder has been run, you should go through each visual answerline and format it as per style guides, as there will likely be errors. Hence, it is recommended (but not required) to make sure that the answerlines for the written portion of a hybrid set are verified and proofreaded before running Storyboarder.

History

2024-03-24: This project was created by Ani Perumalla to handle setup for mirrors of Untitled Film Set (privately, since the set was used for testing and was not yet played at that time).

2024-09-27: The scripts were updated to automatically populate answerlines with information about film directors, using the tmdbv3api package.

2024-11-14: The project was shared publicly on the HSQB forums.

Feedback

Please create an issue. Pull requests are welcomed!

Footnotes

1. The slide template uses the Wong colorblind-friendly palette. ↩

2. Note that this template assumes that each visual question is comprised of exactly 8 slides. However, the scripts can handle any question length. ↩

3. All other columns (Difficulty, Continent, etc.) are just for benefit of the writers and are not actually used in the processing. ↩