# chiptime

> Recovery-grade FIT file processing: parse anything, lose nothing silently, explain everything.

chiptime is recovery-grade FIT file processing: parse anything, lose
nothing silently, explain everything. Python library + CLI, zero
runtime dependencies, MIT; deterministic canonical JSON; stable
machine codes for errors, warnings, provenance, and insights.

Rules for agents working with chiptime: FIT sentinels decode to null,
not values — and null never equals 0 (coasting is 0 W, dropout is
null). Check `provenance[]` before trusting any repaired or
reinterpreted field. Prefer `lenient` mode; route on CLI exit codes
(0 clean, 2 recovered-with-loss, 3 unusable, 4 not-FIT, 64 usage).
Thresholds (FTP, zones, HR anchors) must come from the user or the
file — never estimate them from the workout itself.


## Start here

- [Home](https://maxgrgrv.github.io/chiptime/index.md)
- [Getting started](https://maxgrgrv.github.io/chiptime/getting-started/index.md)

## Guides

- [Built for agents](https://maxgrgrv.github.io/chiptime/guides/agents/index.md)
- [Analyze workouts](https://maxgrgrv.github.io/chiptime/guides/analyze/index.md)
- [The conformance corpus](https://maxgrgrv.github.io/chiptime/guides/corpus/index.md)
- [Parse anything](https://maxgrgrv.github.io/chiptime/guides/parse-anything/index.md)
- [Repair crash files](https://maxgrgrv.github.io/chiptime/guides/repair/index.md)
- [Storing the output](https://maxgrgrv.github.io/chiptime/guides/storage/index.md)

## Reference

- [Python API — core](https://maxgrgrv.github.io/chiptime/reference/api-core/index.md)
- [Python API — metrics](https://maxgrgrv.github.io/chiptime/reference/api-metrics/index.md)
- [Python API — model](https://maxgrgrv.github.io/chiptime/reference/api-model/index.md)
- [CLI](https://maxgrgrv.github.io/chiptime/reference/cli/index.md)
- [Codes registry](https://maxgrgrv.github.io/chiptime/reference/codes/index.md)
- [ACTIVITY_MESSAGE_MISSING](https://maxgrgrv.github.io/chiptime/reference/codes/activity-message-missing/index.md)
- [COASTING_HIGH](https://maxgrgrv.github.io/chiptime/reference/codes/coasting-high/index.md)
- [COMPRESSED_AND_EXPLICIT_TIMESTAMP](https://maxgrgrv.github.io/chiptime/reference/codes/compressed-and-explicit-timestamp/index.md)
- [DEV_DATA_ID_MISSING](https://maxgrgrv.github.io/chiptime/reference/codes/dev-data-id-missing/index.md)
- [DEV_FIELD_NAME_SYNTHESIZED](https://maxgrgrv.github.io/chiptime/reference/codes/dev-field-name-synthesized/index.md)
- [DEV_FIELD_RESOLVED_LATE](https://maxgrgrv.github.io/chiptime/reference/codes/dev-field-resolved-late/index.md)
- [DEV_INDEX_REDEFINED](https://maxgrgrv.github.io/chiptime/reference/codes/dev-index-redefined/index.md)
- [DISTANCE_DECREASES](https://maxgrgrv.github.io/chiptime/reference/codes/distance-decreases/index.md)
- [DISTANCE_FROZEN](https://maxgrgrv.github.io/chiptime/reference/codes/distance-frozen/index.md)
- [DISTANCE_RESET](https://maxgrgrv.github.io/chiptime/reference/codes/distance-reset/index.md)
- [ENHANCED_PAIR_DISAGREES](https://maxgrgrv.github.io/chiptime/reference/codes/enhanced-pair-disagrees/index.md)
- [ENHANCED_PAIR_MERGED](https://maxgrgrv.github.io/chiptime/reference/codes/enhanced-pair-merged/index.md)
- [FIELD_RAW_SALVAGED](https://maxgrgrv.github.io/chiptime/reference/codes/field-raw-salvaged/index.md)
- [FIT_BASE_TYPE_INVALID](https://maxgrgrv.github.io/chiptime/reference/codes/fit-base-type-invalid/index.md)
- [FIT_CRC_MISMATCH](https://maxgrgrv.github.io/chiptime/reference/codes/fit-crc-mismatch/index.md)
- [FIT_CRC_MISSING](https://maxgrgrv.github.io/chiptime/reference/codes/fit-crc-missing/index.md)
- [FIT_DATA_SIZE_MISMATCH](https://maxgrgrv.github.io/chiptime/reference/codes/fit-data-size-mismatch/index.md)
- [FIT_DEFINITION_INVALID](https://maxgrgrv.github.io/chiptime/reference/codes/fit-definition-invalid/index.md)
- [FIT_EMPTY](https://maxgrgrv.github.io/chiptime/reference/codes/fit-empty/index.md)
- [FIT_FIELD_SIZE_INVALID](https://maxgrgrv.github.io/chiptime/reference/codes/fit-field-size-invalid/index.md)
- [FIT_HEADER_CRC_MISMATCH](https://maxgrgrv.github.io/chiptime/reference/codes/fit-header-crc-mismatch/index.md)
- [FIT_HEADER_INVALID](https://maxgrgrv.github.io/chiptime/reference/codes/fit-header-invalid/index.md)
- [FIT_MISSING_TIMESTAMP_ANCHOR](https://maxgrgrv.github.io/chiptime/reference/codes/fit-missing-timestamp-anchor/index.md)
- [FIT_NO_CONTENT](https://maxgrgrv.github.io/chiptime/reference/codes/fit-no-content/index.md)
- [FIT_TOO_SMALL](https://maxgrgrv.github.io/chiptime/reference/codes/fit-too-small/index.md)
- [FIT_TRAILING_JUNK](https://maxgrgrv.github.io/chiptime/reference/codes/fit-trailing-junk/index.md)
- [FIT_TRUNCATED](https://maxgrgrv.github.io/chiptime/reference/codes/fit-truncated/index.md)
- [FIT_UNDEFINED_LOCAL_TYPE](https://maxgrgrv.github.io/chiptime/reference/codes/fit-undefined-local-type/index.md)
- [GPS_SPIKES_DROPPED](https://maxgrgrv.github.io/chiptime/reference/codes/gps-spikes-dropped/index.md)
- [HR_DRIFT_HIGH](https://maxgrgrv.github.io/chiptime/reference/codes/hr-drift-high/index.md)
- [HR_EXPANSION_NO_ANCHOR](https://maxgrgrv.github.io/chiptime/reference/codes/hr-expansion-no-anchor/index.md)
- [HR_FLATLINE](https://maxgrgrv.github.io/chiptime/reference/codes/hr-flatline/index.md)
- [HR_IMPLAUSIBLE](https://maxgrgrv.github.io/chiptime/reference/codes/hr-implausible/index.md)
- [LAP_COVERAGE_GAP](https://maxgrgrv.github.io/chiptime/reference/codes/lap-coverage-gap/index.md)
- [LAP_ZERO_DURATION](https://maxgrgrv.github.io/chiptime/reference/codes/lap-zero-duration/index.md)
- [LOCAL_TIMESTAMP_IMPLAUSIBLE](https://maxgrgrv.github.io/chiptime/reference/codes/local-timestamp-implausible/index.md)
- [MOVEMENT_WITHOUT_DISTANCE](https://maxgrgrv.github.io/chiptime/reference/codes/movement-without-distance/index.md)
- [NONFINITE_FLOAT_NULLED](https://maxgrgrv.github.io/chiptime/reference/codes/nonfinite-float-nulled/index.md)
- [NOT_FIT_FORMAT](https://maxgrgrv.github.io/chiptime/reference/codes/not-fit-format/index.md)
- [NULL_ISLAND_DROPPED](https://maxgrgrv.github.io/chiptime/reference/codes/null-island-dropped/index.md)
- [NUM_SESSIONS_MISMATCH](https://maxgrgrv.github.io/chiptime/reference/codes/num-sessions-mismatch/index.md)
- [PACING_NEGATIVE_SPLIT](https://maxgrgrv.github.io/chiptime/reference/codes/pacing-negative-split/index.md)
- [PACING_POSITIVE_SPLIT](https://maxgrgrv.github.io/chiptime/reference/codes/pacing-positive-split/index.md)
- [PARTIAL_RECORD_DISCARDED](https://maxgrgrv.github.io/chiptime/reference/codes/partial-record-discarded/index.md)
- [PII_STRIPPED](https://maxgrgrv.github.io/chiptime/reference/codes/pii-stripped/index.md)
- [POOL_LENGTH_IMPLAUSIBLE](https://maxgrgrv.github.io/chiptime/reference/codes/pool-length-implausible/index.md)
- [POOL_ZERO_LENGTH](https://maxgrgrv.github.io/chiptime/reference/codes/pool-zero-length/index.md)
- [POWER_IMPLAUSIBLE](https://maxgrgrv.github.io/chiptime/reference/codes/power-implausible/index.md)
- [PREAMBLE_GARBAGE_SKIPPED](https://maxgrgrv.github.io/chiptime/reference/codes/preamble-garbage-skipped/index.md)
- [RECORDS_OUTSIDE_SESSIONS](https://maxgrgrv.github.io/chiptime/reference/codes/records-outside-sessions/index.md)
- [RECORDS_REORDERED](https://maxgrgrv.github.io/chiptime/reference/codes/records-reordered/index.md)
- [RELATIVE_TIMESTAMP](https://maxgrgrv.github.io/chiptime/reference/codes/relative-timestamp/index.md)
- [REPAIR_ACTIVITY_SYNTHESIZED](https://maxgrgrv.github.io/chiptime/reference/codes/repair-activity-synthesized/index.md)
- [REPAIR_EVENTS_SYNTHESIZED](https://maxgrgrv.github.io/chiptime/reference/codes/repair-events-synthesized/index.md)
- [REPAIR_FILE_ID_SYNTHESIZED](https://maxgrgrv.github.io/chiptime/reference/codes/repair-file-id-synthesized/index.md)
- [REPAIR_LAP_SYNTHESIZED](https://maxgrgrv.github.io/chiptime/reference/codes/repair-lap-synthesized/index.md)
- [REPAIR_LOCAL_TIMESTAMP_DROPPED](https://maxgrgrv.github.io/chiptime/reference/codes/repair-local-timestamp-dropped/index.md)
- [REPAIR_NOTHING_TO_SALVAGE](https://maxgrgrv.github.io/chiptime/reference/codes/repair-nothing-to-salvage/index.md)
- [REPAIR_REENCODED](https://maxgrgrv.github.io/chiptime/reference/codes/repair-reencoded/index.md)
- [REPAIR_SESSION_SYNTHESIZED](https://maxgrgrv.github.io/chiptime/reference/codes/repair-session-synthesized/index.md)
- [RESYNC_SKIPPED_BYTES](https://maxgrgrv.github.io/chiptime/reference/codes/resync-skipped-bytes/index.md)
- [SESSION_REBUILT](https://maxgrgrv.github.io/chiptime/reference/codes/session-rebuilt/index.md)
- [STREAM_STOPPED_AT_DEFECT](https://maxgrgrv.github.io/chiptime/reference/codes/stream-stopped-at-defect/index.md)
- [STRING_DECODE_REPLACED](https://maxgrgrv.github.io/chiptime/reference/codes/string-decode-replaced/index.md)
- [STRING_UNTERMINATED](https://maxgrgrv.github.io/chiptime/reference/codes/string-unterminated/index.md)
- [SUMMARY_AVG_EXCEEDS_MAX](https://maxgrgrv.github.io/chiptime/reference/codes/summary-avg-exceeds-max/index.md)
- [SUMMARY_NEGATIVE_TOTAL](https://maxgrgrv.github.io/chiptime/reference/codes/summary-negative-total/index.md)
- [TIMER_STOP_SYNTHESIZED](https://maxgrgrv.github.io/chiptime/reference/codes/timer-stop-synthesized/index.md)
- [TIMER_STOP_WITHOUT_START](https://maxgrgrv.github.io/chiptime/reference/codes/timer-stop-without-start/index.md)
- [TIMESTAMP_ANCHOR_FROM_FILE_ID](https://maxgrgrv.github.io/chiptime/reference/codes/timestamp-anchor-from-file-id/index.md)
- [TIMESTAMP_DECLARED_AS_BYTES](https://maxgrgrv.github.io/chiptime/reference/codes/timestamp-declared-as-bytes/index.md)
- [TIMESTAMPS_AFTER_CREATION](https://maxgrgrv.github.io/chiptime/reference/codes/timestamps-after-creation/index.md)
- [TRUNCATED_TAIL_SALVAGED](https://maxgrgrv.github.io/chiptime/reference/codes/truncated-tail-salvaged/index.md)
- [UNKNOWN_MESSAGES_OMITTED](https://maxgrgrv.github.io/chiptime/reference/codes/unknown-messages-omitted/index.md)
- [UNRELIABLE_ABSOLUTE_TIME](https://maxgrgrv.github.io/chiptime/reference/codes/unreliable-absolute-time/index.md)
- [VIRTUAL_GPS_EXEMPT](https://maxgrgrv.github.io/chiptime/reference/codes/virtual-gps-exempt/index.md)
- [WORKOUT_STRUCTURE](https://maxgrgrv.github.io/chiptime/reference/codes/workout-structure/index.md)
- [ZERO_DURATION_SESSION](https://maxgrgrv.github.io/chiptime/reference/codes/zero-duration-session/index.md)
- [ZIP_ENTRIES_CHAINED](https://maxgrgrv.github.io/chiptime/reference/codes/zip-entries-chained/index.md)

## Migrate

- [Overview](https://maxgrgrv.github.io/chiptime/switch/index.md)
- [From fitdecode](https://maxgrgrv.github.io/chiptime/switch/from-fitdecode/index.md)
- [From fitparse](https://maxgrgrv.github.io/chiptime/switch/from-fitparse/index.md)

## Concepts

- [Architecture](https://maxgrgrv.github.io/chiptime/concepts/architecture/index.md)
- [The contract](https://maxgrgrv.github.io/chiptime/concepts/contract/index.md)
- [Determinism](https://maxgrgrv.github.io/chiptime/concepts/determinism/index.md)
- [Edge-case taxonomy](https://maxgrgrv.github.io/chiptime/concepts/edge-cases/index.md)

## Articles

- [A conformance corpus for FIT files: 104 edge cases with committed expected outputs](https://maxgrgrv.github.io/chiptime/blog/a-conformance-corpus-for-fit-files-104-edge-cases-with-committed-expected-outputs/index.md)
- [Meet chiptime: your workout data, fully yours](https://maxgrgrv.github.io/chiptime/blog/meet-chiptime-your-workout-data-fully-yours/index.md)