Troubleshooting

Song not appearing in the Library

Cause: The file extension is not recognised, or the Library has not been reloaded.

Fix:

1. Confirm the file extension is .json, .skysheet, or .txt.
2. Press Reload songs in the desktop GUI without restarting.
3. If still missing, check that the file is directly inside the songs/ folder, not in a subfolder.

“Failed to parse” or parse error on launch

Cause: The file content is not valid JSON, or the sheet uses a schema version the current parser does not support.

Fix:

1. Open the file in a text editor. Confirm it contains a JSON object starting with {.
2. Re-export the sheet from the Sky Music editor.
3. If the error persists, open a GitHub issue and attach the error message (not the sheet file itself).

Notes sound late or ahead of the music

Cause A — FPS mismatch: The FPS setting in Sky Auto Player does not match the FPS configured inside Sky.

Fix: Open the per-song settings and set the FPS to match Sky’s frame rate (30 or 60).

Cause B — Tempo mismatch: The tempo multiplier is not 1.0.

Fix: Reset the tempo multiplier to 1.0 in per-song settings.

Cause C — System load: Heavy CPU load causes Windows scheduling jitter, which increases sender-side latency beyond what the adaptive lead can compensate.

Fix: Close background applications. Consider enabling a tuning preset for weak PCs via the --tuning flag. See the full FAQ.

Note: Sky Auto Player controls when keystrokes are sent. When the game processes them depends on the game’s own sampling loop and Windows scheduling — these factors are outside the player’s control.

Hold notes not registering (releasing too early)

Cause: The hold duration at the configured FPS is shorter than the game’s minimum registration time for that key.

Fix: In per-song settings, switch from 1.0 frames to 1.25 frames or 1.5 frames. The FPS setting must match the FPS inside Sky for hold timing to be correct.

Game does not receive any input

Cause A — Focus: The game window does not have focus when playback starts.

Fix: Switch to the game window before pressing the play hotkey. Sky Auto Player sends keystrokes to the active window; if the game is not focused, keystrokes go elsewhere.

Cause B — Hotkey not set: The play hotkey is not bound or conflicts with another application.

Fix: Open the command palette (/) and check hotkey bindings.

Cause C — Wrong key layout: The key layout profile does not match the keyboard layout in use inside Sky.

Fix: Verify the layout profile in settings matches what Sky shows.

Windows SmartScreen warning on launch

Cause: The installer or an installed binary did not pass the expected Authenticode identity or was not downloaded from the official Sky Auto Player GitHub Releases page.

Fix: Do not bypass the warning. Delete the download and obtain the installer and .exe.sig sidecar again from the official Sky Auto Player GitHub Releases page.

Updating manually

Cause: The official Tauri updater could not stage or execute the current-user installer.

Fix:

1. Retry Update and Restart from the in-app update notice.
2. If it still fails, uninstall only after preserving app data, then download the current canonical NSIS installer from the official Sky Auto Player GitHub Releases page.
3. Do not use a v3 ZIP, MANIFEST.json, or standalone updater executable for v4.

The HUD shows high timing jitter

Cause: The HUD’s jitter metric reflects sender-side dispatch variance. High values indicate OS scheduling pressure on your machine.

Fix: Close background applications. Try a tuning preset. Note that sender-side jitter does not directly translate to audible timing errors — the game’s sampling rate is often the larger factor.

Known limitations

These issues cannot be fixed from the player side and are documented as known constraints:

• Game-side timing: The game decides when to register keystrokes. Sky Auto Player cannot override the game’s input polling rate.
• Very fast passages: Extremely dense arpeggios at high BPM may exceed the game’s ability to register individual notes, regardless of how precisely they are sent.
• Windows only: MMCSS real-time scheduling and SendInput are Windows APIs. macOS and Linux are not supported and are not on the roadmap.
• Unofficial project: Sky Auto Player is not affiliated with thatgamecompany. Automated playback may conflict with Sky’s Terms of Service.