Skip to content
iRaceDeck

Vocabulary

Everything a callouts.json may reference by name, and nothing else: the variables a step plays, the conditions an if branches on, and the cases a case step maps. All three are registered in iRaceDeck’s code with the descriptions you read here; a script names them and can never define one. A name that is not on this page is an unknown reference, and an entry that uses one is skipped when the script is compiled, with the name in the log.

Used by lists the callouts whose bundled entries name the item, included fragments walked — it links to the callout reference, where you can see the entry that uses it. An item no bundled entry uses is still yours to use. The vocabulary is published generously on purpose: it is exactly what bounds the phrasings a pack can express, so if a phrasing you want has no variable or case here, that is a request to make rather than a workaround to find.

This page is generated from the code, and a test fails when the two drift apart, so it matches the release it documents.

46 variables, 24 conditions and 7 cases.

Variables

A variable resolves at fire time to one clip, or to a pool it picks a take from — a number, a name, a line chosen by the sim's state. Write it as {{name}}, or as { "var": "name" }. A variable that resolves to nothing aborts the callout unless the step sits inside an optional.

{{cornerName.clip}}

The name of the corner the driver is approaching, drawn from the corner-names group (one clip per corner, named by its slug — corner-names/eau-rouge, corner-names/turn-5). Nothing when the voice has no clip for that corner, which skips the callout rather than half-saying it.

Used by: pit-crew.corner-name-approaching

{{gap.decimal}}

The tenths of the live gap, 0–9, drawn from the lap-time-decimal group (lap-time-decimal/6 is "point six seconds"). Read live at speak time; nothing when gap.readoutIntro has nothing.

Used by: pit-crew.gap-threshold, pit-crew.gap-trend

{{gap.line}}

The trend line for the gap that just changed, drawn from the gap group by side and direction: gap/ahead-closing, gap/ahead-opening, gap/behind-closing, gap/behind-opening. A complete sentence on its own.

Used by: pit-crew.gap-trend

{{gap.readoutIntro}}

The lead-in of the live gap readout ("Gap is"), from gap/readout-intro. Resolves only when the gap can be read at speak time — under a minute, on the same lap, and still to the car the line named — and gap.second and gap.decimal resolve on exactly the same test, so the three are spoken together or not at all.

Used by: pit-crew.gap-threshold, pit-crew.gap-trend

{{gap.second}}

The whole seconds of the live gap, 0–59, drawn from the lap-time-second group (lap-time-second/1 is "one"). Read live at speak time; nothing when gap.readoutIntro has nothing.

Used by: pit-crew.gap-threshold, pit-crew.gap-trend

{{gap.thresholdLine}}

The line for a gap that just dropped under the driver's alert threshold, drawn from the gap group by side: gap/threshold-ahead (we have caught the car ahead) or gap/threshold-behind (the car behind is right with us). A complete sentence on its own.

Used by: pit-crew.gap-threshold

{{incident.points}}

The penalty points the incident cost, as the sim scored it, spoken as a whole clause from the incidents group (incidents/points-2 is "That cost us two penalty points."). Nothing for a light contact worth no points, or for a count the voice has no clip for — a whole clause, so a script may make it optional and the type line still stands on its own.

Used by: pit-crew.incident-collision-car, pit-crew.incident-collision-world, pit-crew.incident-contact-car, pit-crew.incident-contact-world

{{lapTime.decimal}}

The tenths of a second (0 to 9), spoken as "point N seconds" — the clip that ends the readout. Draws from the lap-time-decimal clip group.

Used by: pit-crew.lap-time-best

{{lapTime.intro}}

The opening line of the lap-time readout: first-good-lap on the driver's first valid lap of the session, best-lap-yet on every later improvement. Draws from the lap-time-intro clip group.

Used by: pit-crew.lap-time-best

{{lapTime.minute}}

The whole-minute part of the lap time, as one clip per minute value; nothing for a lap under a minute. Draws from the lap-time-minute clip group — a minute the voice has no clip for aborts the readout.

Used by: pit-crew.lap-time-best

{{lapTime.second}}

The whole-second part of the lap time (0 to 59), one clip per value with a trailing comma. Draws from the lap-time-second clip group.

Used by: pit-crew.lap-time-best

{{opponentFlag.number}}

The flagged car's race position as a spoken number, drawn from the position-number group (position-number/4 is "P4"). Read live at speak time — class position in a multi-class race — and falling back to the position the event carried. Only the ahead lines name a position; part of the sentence, so a number that cannot be resolved skips the whole line rather than leaving a gap.

Used by: pit-crew.opponent-flag-black-ahead, pit-crew.opponent-flag-disqualify-ahead, pit-crew.opponent-flag-furled-ahead, pit-crew.opponent-flag-meatball-ahead

{{opponentPit.number}}

The pitting car's race position as a spoken number, drawn from the position-number group (position-number/4 is "P4"). Read live at speak time — class position in a multi-class race — and falling back to the position the event carried. Part of the sentence, so a number that cannot be resolved skips the whole line rather than leaving a gap.

Used by: pit-crew.opponent-pit-nearby

{{overtake.lost.comeOn}}

The "Come on, <name>." opener of the lost-position line, a full clip per driver name from the position-overtake-come-on group (position-overtake-come-on/driver is the generic fallback). A complete sentence on its own, so the bundled script makes it optional: a voice without the chosen name's clip skips it and the line still plays.

Used by: pit-crew.overtake-lost

{{pitSpeed.limitIntro}}

The lead-in to the spoken pit-speed limit ("The pit speed limit is"), from the session-start/pit-speed-intro clip. Nothing to say while the session conditions are unknown, so keep it in one optional clause with the number and the unit.

Used by: pit-crew.no-limiter-entry

{{pitSpeed.limitNumber}}

The pit-speed limit as a number, from the session-start-speed-numbers/<limit> clip. The group covers the limits iRacing actually uses rather than every number, so a limit the voice has no clip for empties the clause instead of rounding to a wrong one.

Used by: pit-crew.no-limiter-entry

{{pitSpeed.limitUnit}}

The pit-speed limit's unit, sentence-final, from the pit-limiter/unit-kmh or pit-limiter/unit-mph clip — recorded apart from the session brief's unit clips, which end on a comma because a temperature follows them there.

Used by: pit-crew.no-limiter-entry

{{position.intro}}

The lead-in of a position readout, chosen by what the lap did: position-intro-better/that-puts-us-to for a gain (or a first fix) in qualifying, position-intro-worse/currently for a loss, a held place, or any lap in a race, where standings do not follow from lap times. A fragment of the sentence — keep it required before position.number.

Used by: pit-crew.position-change

{{position.number}}

The driver's position as a spoken number, drawn from the position-number group (position-number/4 is "P4"): the position the lap just completed left the driver in during qualifying, and the live position at the moment it is spoken during a race — class position in a multi-class session either way. The point of the readout, so a script keeps it required.

Used by: pit-crew.position-change

{{position.pole}}

The self-contained pole line, position-intro-pole/that-puts-us-on-pole ("That puts us on pole.") — a complete sentence that replaces the intro and the number when the lap put the driver on pole in qualifying.

Used by: pit-crew.position-change

{{positionReadout.intro}}

The "We're currently" lead-in of a position readout, from position-intro-worse/currently. Resolves to nothing for a second readout within 30 seconds of the last one that moved at most one place — the number is then spoken bare — so the bundled script wraps it in an optional clause; a script that wants the lead-in every time drops the optional. Resolving it also records this readout for the next one's decision, so name it at most once per entry.

Used by: pit-crew.overtake-gained-position, pit-crew.overtake-lost-position

{{positionReadout.number}}

The driver's current race position as a spoken number, drawn from the position-number group (position-number/4 is "P4"), read live at the moment it is spoken — class position in a multi-class race. The whole point of the readout, so a script keeps it required.

Used by: pit-crew.overtake-gained-position, pit-crew.overtake-lost-position

{{raceEnd.greeting}}

The driver's name as a race-end greeting, one clip per name the voice recorded (the generic driver clip when no name is picked). Draws from the race-end-greeting clip group — a name the voice lacks resolves to nothing, so keep it optional.

Used by: pit-crew.race-end

{{raceEnd.podiumThird}}

The whole third-place line — we made the podium. Draws the podium-third line from the race-end clip group.

Used by: pit-crew.race-end

{{raceEnd.position}}

The final position as a spoken number — the class position in a multi-class race, the overall position otherwise. Draws from the position-number clip group; a position the voice has no clip for aborts the readout.

Used by: pit-crew.race-end

{{raceEnd.raceOverResultIs}}

The lead-in of the fourth-or-worse readout — the race is over, the final result for us is. A fragment of a sentence: the position number must follow it. Draws the race-over-result-is line from the race-end clip group.

Used by: pit-crew.race-end

{{raceEnd.secondPlace}}

The whole second-place line. Draws the second-place line from the race-end clip group.

Used by: pit-crew.race-end

{{raceEnd.weWon}}

The whole winning line — we won, well done. Draws the we-won line from the race-end clip group.

Used by: pit-crew.race-end

{{raceStart.airTempNumber}}

The air temperature as a whole number in the driver's display unit. Draws from the session-start-temp-numbers clip group; a reading outside the recorded range aborts the clause it sits in.

Used by: pit-crew.race-start

{{raceStart.degreesUnit}}

The temperature unit word — degrees celsius or degrees fahrenheit, per the driver's display setting. Draws the degrees-celsius and degrees-fahrenheit lines from the session-start clip group.

Used by: pit-crew.race-start

{{raceStart.greeting}}

The race-start greeting with the driver's name — "time to race, <name>" as one clip per name the voice recorded (the generic driver clip when no name is picked). Draws from the race-start-greeting clip group; a name the voice lacks resolves to nothing, so keep it optional.

Used by: pit-crew.race-start

{{raceStart.position}}

The grid position as a spoken number. Draws from the position-number clip group; a position the voice has no clip for resolves to nothing and aborts the clause it sits in.

Used by: pit-crew.race-start

{{raceStart.trackTempNumber}}

The track temperature as a whole number in the driver's display unit. Draws from the session-start-temp-numbers clip group; a reading outside the recorded range aborts the clause it sits in.

Used by: pit-crew.race-start

{{raceStart.wetness}}

The track wetness state as a word — dry, mostly dry, very lightly wet, lightly wet, moderately wet, very wet or extremely wet. Draws the wetness-<state> lines from the session-start clip group.

Used by: pit-crew.race-start

{{raceStatus.intro}}

The lead-in of a non-leader status update — "we're currently". Draws the currently line from the position-intro-worse clip group, shared with the position callout.

Used by: pit-crew.race-status

{{raceStatus.number}}

The driver's live position as a spoken number — the class position in a multi-class race, the overall position otherwise. Draws from the position-number clip group; a position the voice has no clip for aborts the readout.

Used by: pit-crew.race-status

{{raceStatus.stillLeading}}

The leader's whole status line — still leading the race, or still leading our class in a multi-class race. Draws the still-leading and still-leading-class lines from the race-status clip group.

Used by: pit-crew.race-status

{{sessionStart.airTempNumber}}

The air temperature as a whole number in the driver's display unit. Draws from the session-start-temp-numbers clip group; a reading outside the recorded range aborts the clause it sits in.

Used by: pit-crew.session-start

{{sessionStart.degreesUnit}}

The temperature unit word — degrees celsius or degrees fahrenheit, per the driver's display setting. Draws the degrees-celsius and degrees-fahrenheit lines from the session-start clip group.

Used by: pit-crew.session-start

{{sessionStart.greeting}}

The session-start greeting with the driver's name — "ok, <name>" as one clip per name the voice recorded. Draws from the session-start-greeting clip group; a name the voice lacks resolves to nothing, so keep it optional.

Used by: pit-crew.session-start

{{sessionStart.sessionLine}}

The line naming the session that just started — practice or qualifying (race is the race-start callout's). Draws the session-practice and session-qualifying lines from the session-start clip group.

Used by: pit-crew.session-start

{{sessionStart.speedNumber}}

The pit speed limit as a whole number in the driver's speed unit. Draws from the session-start-speed-numbers clip group, which covers the limits iRacing uses; a limit with no clip resolves to nothing and aborts the clause it sits in.

Used by: pit-crew.session-start

{{sessionStart.speedUnit}}

The speed unit word after the pit speed limit — kilometers per hour or miles per hour, per the driver's display setting. Draws the speed-unit-kmh and speed-unit-mph lines from the session-start clip group.

Used by: pit-crew.session-start

{{sessionStart.trackTempNumber}}

The track temperature as a whole number in the driver's display unit. Draws from the session-start-temp-numbers clip group; a reading outside the recorded range aborts the clause it sits in.

Used by: pit-crew.session-start

{{sessionStart.wetness}}

The track wetness state as a word — dry, mostly dry, very lightly wet, lightly wet, moderately wet, very wet or extremely wet. Draws the wetness-<state> lines from the session-start clip group.

Used by: pit-crew.session-start

{{spotterClip}}

The spotter call for the car-presence change that just happened, drawn from the spotter group: "Car left", "Two cars right", "Three wide", the combined swaps ("Clear right, car left"), the 2-to-1 de-escalation, "Clear", and the still-there reminders — inside/outside terms on an oval. Chosen by the spotter engine per transition and read when it fires, so it is the whole call.

Used by: pit-crew.spotter-call, pit-crew.spotter-info

Conditions

A condition answers yes or no at fire time. Write it in an if step — { "if": "name", "then": [ … ], "else": [ … ] } — and negate it with a single leading !. That ! is the only operator the format has.

flag.furledStillShown

The furled black flag is still being shown at speak time; speaking it marks the raise as announced.

Used by: pit-crew.flag-furled

flag.furledWithdrawn

An announced furled flag has been withdrawn; speaking it consumes the announcement.

Used by: pit-crew.flag-furled-cleared

lapTime.hasMinuteComponent

The lap is a minute or longer, so the minute word is spoken before the seconds. A pack may drop the minute with optional for a terse register; the assumed minute only holds where it is 1.

Used by: pit-crew.lap-time-best

limiter.stillEngagedOffPitRoad

The car has a pit limiter and it is still engaged out on the track, according to live telemetry when the line comes to speak — about a second and a half after leaving pit road. Wrap the on-track warning's whole body in it so a driver who has already switched the limiter off hears nothing. False on a car without a limiter or when telemetry is unavailable.

Used by: pit-crew.limiter-on-track

limiter.stillMissingOnPitRoad

The car has a pit limiter and it is still NOT engaged on pit road, according to live telemetry when the line comes to speak — a couple of seconds after the pit-entry reminder. Wrap the missing-limiter warning's whole body in it so a driver who engaged the limiter in the meantime hears nothing. False on a car without a limiter or when telemetry is unavailable.

Used by: pit-crew.limiter-missing

pitStatus.stillBadAngle

The car is still at a bad angle in the pit box according to live telemetry, or telemetry is unavailable. Wrap a repeat nag's whole body in it so a nag that waited behind a longer line stays silent once the driver has corrected; unknown telemetry counts as still wrong, never as fixed.

Used by: pit-crew.pit-status-bad-angle-repeat

pitStatus.stillTooFarBack

The car is still too far back in the pit box according to live telemetry, or telemetry is unavailable. Wrap a repeat nag's whole body in it so a nag that waited behind a longer line stays silent once the driver has corrected; unknown telemetry counts as still wrong, never as fixed.

Used by: pit-crew.pit-status-too-far-back-repeat

pitStatus.stillTooFarForward

The car is still too far forward in the pit box according to live telemetry, or telemetry is unavailable. Wrap a repeat nag's whole body in it so a nag that waited behind a longer line stays silent once the driver has corrected; unknown telemetry counts as still wrong, never as fixed.

Used by: pit-crew.pit-status-too-far-forward-repeat

pitStatus.stillTooFarLeft

The car is still too far left in the pit box according to live telemetry, or telemetry is unavailable. Wrap a repeat nag's whole body in it so a nag that waited behind a longer line stays silent once the driver has corrected; unknown telemetry counts as still wrong, never as fixed.

Used by: pit-crew.pit-status-too-far-left-repeat

pitStatus.stillTooFarRight

The car is still too far right in the pit box according to live telemetry, or telemetry is unavailable. Wrap a repeat nag's whole body in it so a nag that waited behind a longer line stays silent once the driver has corrected; unknown telemetry counts as still wrong, never as fixed.

Used by: pit-crew.pit-status-too-far-right-repeat

qualifying.tailIsSpeakable

The qualifying session is lap-limited and the laps-left count is known, so a laps-left tail can follow the invalidated line. False in time-limited qualifying, where a lap count means nothing.

Used by: pit-crew.qualifying-invalidation-lap-invalidated

raceStatus.isLeading

The driver is leading at speak time — first overall, or first in class in a multi-class race. The bundled script speaks the still-leading line instead of the position readout when this holds.

Used by: pit-crew.race-status

readback.fastRepairSkipped

The car is damaged, the series offers fast repair, and fast repair is NOT queued — worth warning the driver about. False on a clean car, so nothing is said about repairs then.

Used by: pit-crew.pit-readback-entry, pit-crew.pit-readback-exit

readback.hasAnyService

At least one service is queued: fuel, any tire, a compound change, fast repair on a damaged car in a series that offers it, or a windshield clean. When false the bundled script plays the empty-fallback line alone instead of a string of negatives.

Used by: pit-crew.pit-readback-entry, pit-crew.pit-readback-exit

readback.isFirstEntry

This is the initial pit-lane entry, not a mid-lane refire after the driver changed the queue — the carrier sentence (the opener) is worth speaking only once.

Used by: pit-crew.pit-readback-entry

readback.limiterReminderDue

The car has a pit limiter and it is not engaged on the initial pit-lane entry, so a reminder is due before the readback. Never true on a mid-lane refire, on the exit readback, or on a car without a limiter.

Used by: pit-crew.pit-readback-entry

session.isPractice

The current session is a practice session.

Used by: no bundled entry — available to a pack all the same

session.isQualifying

The current session is a qualifying session (open or lone).

Used by: no bundled entry — available to a pack all the same

session.isRace

The current session is a race session (anything that is not practice or qualifying).

Used by: no bundled entry — available to a pack all the same

setupWarning.qualifyingMismatch

The session is qualifying and the loaded setup's name looks like a race setup, per the driver's setup-name patterns — worth a double-check-your-setup nudge. Never true in practice, and false when the warning is switched off or no pattern matches.

Used by: pit-crew.session-start

setupWarning.raceMismatch

The loaded setup's name looks like a qualifying setup at the start of a race, per the driver's setup-name patterns — worth a double-check-your-setup nudge. False when the warning is switched off or no pattern matches.

Used by: pit-crew.race-start

Cases

A case resolves at fire time to one of its declared keys, and a case step maps keys to steps: { "case": "name", "of": { "key": [ … ], "default": [ … ] } }. A key not in of takes the default branch, or plays nothing when there is none; several keys may map to the same line, and a key may map to [] to say nothing about it. A key that is not declared below is refused when the script is compiled.

overtake.gainedReaction

Which reaction a gained overtake earns: a podium place (first, second or third) taken overall or in class, or any other position. Exactly one key applies per pass.

leader
The pass took the overall lead of a single-class race.
leader-class
The pass took the class lead in a multi-class race.
p2
The pass put the driver second overall in a single-class race.
p2-class
The pass put the driver second in class in a multi-class race.
p3
The pass put the driver third overall in a single-class race — onto the podium.
p3-class
The pass put the driver third in class in a multi-class race.
other
Any other position — the plain nice-pass line; the position itself follows in the separate readout.

Used by: pit-crew.overtake-gained

position.readoutShape

Which shape the position readout takes for the lap just completed: an invalidated qualifying lap, a lap that put the driver on pole, or the standard intro and number. Exactly one applies per lap; the invalid-lap shape takes precedence.

invalid-lap
A qualifying lap iRacing did not count (track limits, a pit-lane violation) — the didn't-count line, then the current position with the plain intro; never the pole line or the better framing.
pole
An improvement to first place in qualifying — the lap put the driver on pole, said as one self-contained line with no number.
standard
Any other readout — the intro (that-puts-us-to for a gain in qualifying, we're-currently otherwise) and the position number.

Used by: pit-crew.position-change

qualifying.lapsLeft

How many counted qualifying laps remain after the invalidated one: none, one to five by count, or plenty above that. Only meaningful when qualifying.tailIsSpeakable holds.

1
One lap left.
2
Two laps left.
3
Three laps left.
4
Four laps left.
5
Five laps left.
out-of-laps
No qualifying laps left — the invalidated lap was the last counted attempt.
plenty
Six or more laps left — more than the counted clips name, so the bundled script reassures rather than counts.

Used by: pit-crew.qualifying-invalidation-lap-invalidated

raceEnd.result

How the race ended for the driver — won, second, third, or fourth or worse — judged on the class position in a multi-class race and the overall position otherwise. Exactly one key applies per finish.

won
Finished first — or first in class in a multi-class race.
second
Finished second (in class, in a multi-class race).
third
Finished third (in class, in a multi-class race) — the last podium step.
other
Finished fourth or worse — the bundled script reads the result-is line and the position number.

Used by: pit-crew.race-end

raceStart.gridPosition

Where the driver starts the race: from pole, from a known position to read out, or unknown. Exactly one key applies per start.

pole
Starting from pole — the driver qualified first.
composed
A known grid position of second or worse, to read out with raceStart.position — a position the voice has no number clip for aborts the clause.
none
No usable grid position — say nothing about the grid.

Used by: pit-crew.race-start

readback.tirePattern

Which tires, or which compound change, are queued for the stop. A compound change covers all four tires and takes precedence over the corner pattern; exactly one key applies per snapshot.

compound-dry
A compound change to dry — covers all four tires, so no corner pattern applies.
compound-wet
A compound change to wet — covers all four tires, so no corner pattern applies.
all
All four tires.
fronts
Both fronts only.
rears
Both rears only.
lefts
Both left-side tires only.
rights
Both right-side tires only.
lf-rr
The left-front and right-rear diagonal.
rf-lr
The right-front and left-rear diagonal.
skip-lf
Three corners — every tire except the left-front.
skip-rf
Three corners — every tire except the right-front.
skip-lr
Three corners — every tire except the left-rear.
skip-rr
Three corners — every tire except the right-rear.
lf
The left-front only.
rf
The right-front only.
lr
The left-rear only.
rr
The right-rear only.
none
No tire change and no compound change queued.

Used by: pit-crew.pit-readback-entry, pit-crew.pit-readback-exit