itpdp/api/POSSIBLE_QUESTIONS.md

# Possible Quiz Questions

This document lists every question template currently generated by the API.

Relevant files:

- `src/party/audio-question-generator.ts`
- `src/party/social-question-generator.ts`
- `src/party/numeric-question-generator.ts`

Notes:

- Dynamic placeholders are shown with angle brackets, for example `<track>` or `<artist>`.
- Every generated question is worth `10` points.
- Choice questions generate shuffled answer options.
- Numeric questions generate a numeric answer range instead of options.
- Not every template is available in every party. A question is only emitted when the required analytics, metadata, answer options, and party size are available.

## Audio metadata choice questions

Audio metadata questions are generated by `buildAudioMetadataQuestion`.

| Template | Correct answer | Required data / condition |
| --- | --- | --- |
| `What song is currently playing?` | Current/selected top song title | A resolvable top song and enough track title options |
| `Which genre is shared by the most party members?` | The highest-ranked shared genre | Shared genre analytics and enough genre options |
| `Which genre is ranked #<rank> in the party's shared genres?` | The genre at that exact rank | Shared genre analytics and enough genre options |
| `Which artist is ranked highest in the shared audio data?` | The highest-ranked fair artist | Fair artist analytics and enough artist options |
| `Which artist is ranked #<rank> in the shared audio data?` | The artist at that exact rank | Fair artist analytics and enough artist options |
| `Which track is ranked highest across the party?` | The top fair shared track | Top fair track is shared by more than one member and enough track options exist |
| `Which track is ranked #<rank> in the party analysis?` | The track at that exact rank | Fair track analytics and enough track options |
| `Which artist appears on "<album>"?` | An artist from the album | A top track with album name and artist metadata, plus enough artist options |
| `Which of these tracks came out first?` | Earliest released track among detailed top tracks | At least two detailed top tracks with album release dates |
| `Which of these tracks came out most recently?` | Latest released track among detailed top tracks | At least two detailed top tracks with album release dates and distinct earliest/latest tracks |
| `What's the longest track by <artist>?` | Longest detailed top track for that artist | At least two detailed top tracks by the same artist with durations |
| `Who performs "<track>"?` | The track's artist | A top track with artist metadata and enough artist options |
| `What is the name of this track by <artist>?` | The track title | A top track with artist metadata and enough track title options; song title is hidden |
| `Which song is this audio clip from?` | Current/selected top song title | A top song exists, differs from the iterated top track, and enough track title options exist; song title is hidden |
| `"<track>" appears on which album?` | The track's album | A top track with album metadata and enough album options |

## Social choice questions

Social questions are generated by `buildSocialQuestion`.

| Template | Correct answer | Required data / condition |
| --- | --- | --- |
| `Who is leading the quiz right now?` | Current quiz leader | At least 2 members and a clear leader in `quizState.scores` |
| `Who looks like the most diverse listener in the party?` | Member with highest genre entropy | At least 2 members and `groupSummary.mostDiverseMember` is available |
| `Who listens the most to "<track>"?` | Member with the highest score for that track | At least 2 members, a fair top track, and a top listener for that track |
| `Which two players share the most musical taste?` | Pair from `groupSummary.mostAlignedPair` | At least 3 members and a resolvable most-aligned pair |

## Numeric questions

Numeric questions are generated by `buildNumericQuestion`.

| Template | Correct answer | Range | Required data / condition |
| --- | --- | --- | --- |
| `What's the release year of <album-or-track>?` | Album release year | Release-year range around correct year | A fair top track with an album release date |
| `What year did "<track>" come out?` | Track album release year | Release-year range around correct year | A detailed fair top track with an album release date |
| `What year did <artist>'s first party track come out?` | Release year of the earliest party track by that artist | Release-year range around correct year | At least two detailed top tracks by the same artist with release dates |
| `For how many players in the party is "<track>" a top track?` | Count of party members whose top tracks include the track | `0` to party member count | A fair top track that resolves to a database track and appears for at least one member |
| `How many players in the party have "<artist>" as a favourite artist?` | Count of party members whose top artists include the artist | `0` to party member count | A fair top artist that resolves to a database artist and appears for at least one member |

## Template count

Current total: **24 question templates**.

- Audio metadata: 15
- Social: 4
- Numeric: 5

## Selection behavior

The generator does not walk this list in a fixed order. For each round:

1. It prioritizes a question family: `audio-metadata`, `numeric`, or `social`.
2. The priority is randomized but penalizes question families used in the last 3 rounds.
3. Each family builds all valid candidates it can from the current party data.
4. Candidates with repeated question keys, subject keys, or text are filtered out.
5. A weighted random candidate is selected, with higher weight for subjects shared by more party members.
6. A song is attached when possible, preferring fresh songs that were not used in prior rounds.