> ## Documentation Index
> Fetch the complete documentation index at: https://docs.questarr.app/llms.txt
> Use this file to discover all available pages before exploring further.

# PLAY TIME

# Play time

Track how long you spend in each game. Sessions are personal: they stay on your Questarr server and
are never sent anywhere.

## Start a timer

* On the **Playing** page (and anywhere a game with status **Playing** is listed), each game has a
  **Start timer** button. Press it when you sit down to play and **Stop** when you are done; the
  button shows the running time.
* You can run **one timer at a time**. While one runs, the other games' buttons are disabled.
* A timer left running is cut off at 24 hours when you stop it, so a forgotten timer does not
  inflate your totals. Questarr tells you when that happens.

## Add time by hand

Open a game's page and scroll to **Playtime**. Pick the day, enter the hours and minutes, and press
**Add session**. For today, the session ends now; for an earlier day it is recorded at noon that
day. A session can be up to 24 hours and cannot end in the future. **Delete** removes a session.

### Edit, merge and split

Sessions you added by hand or recorded with the timer can be corrected from the same list; Playnite and
Steam sessions (and the estimated ones imported from other launchers) stay as they were reported and can
only be deleted. A timer that is still running cannot be changed until you stop it.

* **Edit** (pencil): change when the session started and stopped. The usual limits apply: at least a
  minute, at most 24 hours, not ending in the future.
* **Split** (scissors): cut a session in two at a time you choose, for instance a timer left running
  overnight. Each part keeps the source and lasts at least a minute.
* **Merge**: tick two or more sessions and press **Merge sessions**. They become one session from the
  earliest start to the latest end. They must overlap or be at most 30 minutes apart, and the result cannot
  exceed 24 hours. The merged session keeps their source when they share one, otherwise it counts as manual.

The Playtime section also shows the game's total and how it compares with the IGDB
[Time to Beat](https://www.igdb.com/) estimate when there is one.

## Finish-by goals

In a game's **Playtime** section, **Finish by** lets you pick a target day for the game. Questarr
compares it with the IGDB Time to Beat (the "normally" estimate) and the time you have already
played (timer, manual, Playnite and estimated Steam sessions all count):

* **Time left to beat** is the Time to Beat minus your total, never below zero.
* **Needed per day** spreads that time over the days from today to the target day, the target day
  included.
* **Your pace** is your average per day over the last 14 days on that game.
* The badge reads **On track** when the pace you need is no higher than your pace, **Behind** when it
  is higher, **Overdue** once the target day has passed, **Done** when the game is marked completed.
  Without a Time to Beat estimate the goal only counts the days down.

A game that has not been played in the last 14 days reads **Behind** as soon as it has time left to
beat, since your recent pace is zero. **Clear goal** removes it. The **Statistics** page lists every
unfinished game with a goal under **Finish-by goals**, soonest first. A goal is a date only: there is
no weekly hours target and no notification when a goal is missed yet.

## Statistics

The **Statistics** page has a **Play time** section with:

* the total time played, the number of sessions and the longest session
* your current and best **play streak** (consecutive days with play; today or yesterday keeps a
  streak alive)
* hours per **week** (last 12) or **month** (last 12)
* your **most played** games, each against its IGDB estimate
* time by **genre** and **platform**

Days, weeks (starting Monday) and months follow your browser's time zone (its IANA name, such as
`Europe/Paris`, so daylight saving time is applied to each session on its own date). A session counts
on the day it started. A timer that is still running is not counted until you stop it.

## Playnite

The [Playnite extension](../extensions/playnite-questarr/README.md) can send each finished session
(`POST /api/integration/play-sessions`, source `playnite`). It is off
by default and needs the **Playnite extension** API key access. A session that starts at the same
instant as a stored `playnite` session for that game is ignored, so a retry never counts twice (a
manual or timer session is not compared: do not also record the same play by hand). The end is the
moment the game closed and the start is derived from the duration Playnite reports (whole seconds),
so these times are estimates and a session near midnight can land on the neighbouring day.

## Steam play time

**Settings → Steam → Steam play time** records the time you play on Steam. Steam only reports a
running total per game (`playtime_forever`), so Questarr remembers the last total it saw and, on each
sync, adds the growth as **one session** that ends at the sync (source `steam`, shown as "Steam ·
estimated"). It needs a saved Steam ID, a Steam Web API key (saved in **Settings → Steam** or set as `STEAM_API_KEY`) and public Steam "Game details".

* It is **off by default**. Turning it on starts from your current totals: the first sync only notes
  them, and a game added to your library later is noted the same way, so no history is invented.
  Turning it off and on again starts over.
* It runs every 6 hours (**Activity → System Tasks → Steam play-time sync**) and with **Sync now**; two
  runs less than 30 minutes apart are merged unless you press **Sync now**.
* **No double counting**: the minutes of timer, manual and Playnite sessions recorded for that game since
  the previous sync are subtracted from the growth. A game with a running timer waits for the next sync.
* A total that Steam lowers is followed without creating a session.
* Estimated sessions count in the totals, the weekly and monthly charts and the per-game and per-genre
  figures, but **not** in the longest session or the streaks, because they say nothing about when or how
  long one sitting lasted. A sync that finds 90 new minutes adds one 90-minute session ending at the sync
  time, whatever the gap since the previous sync. Charts place it on its inferred start date, which can
  differ from the day you actually played, so read weekly and monthly totals with that in mind.
* Other launchers (GOG, Epic, EA app, Ubisoft Connect) are not read directly. Play them through Playnite
  to get sessions from its extension.

## What is stored

Each session records the game, when it started, when it ended (empty while the timer runs) and its
source: `timer`, `manual`, `playnite`, `playnite_import` or `steam` (both estimated, see above). The Steam sync keeps its
last totals per game in a small per-user document in the system configuration, so it needs no table. Sessions are deleted with their game. They are included when you move from SQLite to
Postgres (`scripts/sqlite-to-pg.ts`).

A goal is one date (`finish_by`, `YYYY-MM-DD`) on the game itself, with no table of its own.

Not included yet: importing historical playtime from Steam (the first sync only notes your totals) or Playnite (the extension only reports new sessions), weekly-hours goals and missed-goal notifications. See
[Questarr-mgmt#71](https://github.com/Doezer/Questarr-mgmt/issues/71).

## GOG play time from Playnite

Playnite already knows how long each GOG game was played. **Import GOG play time into Questarr**
(Playnite extension 1.3.0, `POST /api/integration/play-time-totals`) sends that total once; Questarr
subtracts the time it already recorded for the game and stores the difference as one estimated
`playnite_import` session ending at the game's last activity. Like Steam estimates, it counts in the
totals but not in the longest session or the streaks. A gap under 10 minutes is ignored, so sending
the same total again adds nothing.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.