Usage Manual · v0.1

DeltaSleep User Guide

Everything you need to know to track, review, and export your sleep — all processed on your phone, never sent anywhere.

Getting started

Install & first launch

DeltaSleep is distributed as a standard Android APK. No Play Store account or Google Services are required.

  1. Download the latest deltasleep-v*.apk from the GitHub Releases page.
  2. On your phone, go to Settings → Apps → Special app access → Install unknown apps and allow your browser or file manager to install APKs.
  3. Open the downloaded file and tap Install.
  4. Launch DeltaSleep. You will be prompted for microphone and notification permissions on the first run.
F-Droid
DeltaSleep is planned for the F-Droid repository. Once listed, installation and automatic updates work without sideloading.

Permissions

DeltaSleep requests exactly three permissions — no more, ever. Here is why each one is needed:

RECORD_AUDIO Analyzes room sounds to detect sleep phases and snoring. Raw audio is never saved to disk.
FOREGROUND_SERVICE Keeps the tracking service alive while the screen is off. Required by Android for long-running background tasks.
POST_NOTIFICATIONS Shows a persistent notification while tracking so you can see it is running and stop it from the notification shade.
No Internet
The INTERNET permission is intentionally absent from the app. The manifest is verified on every CI run — the build will fail if it is ever added. Your audio analysis stays on your device.

Tracking

Starting a session

Open DeltaSleep and tap Start Sleep on the home screen.

  1. The app requests microphone permission if not yet granted.
  2. A foreground service starts and a persistent notification appears in your notification shade — this is normal and expected.
  3. The DSP library calibrates to the ambient noise level of your room for the first few seconds.
  4. The screen navigates automatically to the Active Sleep screen and tracking begins.
Tip — before you tap
Place your phone face-down on the mattress or a nearby nightstand before tapping Start Sleep. Position matters for accuracy — see Phone placement below.

Active sleep screen

While tracking is running the app displays a real-time view of the audio signals being processed. The screen is kept on so you can glance at it before you fall asleep.

What you see on the active screen
Phase badgeAWAKE / LIGHT / DEEP — updates every 30 s
Elapsed timerHH:MM:SS — time since session start
Live signal chartLast 3 minutes of audio level, sound texture, and snore-band energy
Phase historyScrollable colour blocks, one per 30 s epoch
Snore eventsCircle per epoch — filled = snore detected
Audio intensityBar chart of RMS energy per epoch
Snore indicatorAnimated pill at the bottom — turns red when snoring is active

Understanding the live charts

The Live signal chart shows three separate signals for the last three minutes. Each is a smoothed line updated roughly every two seconds:

  • Audio level — overall microphone RMS energy. Spikes when you move or speak.
  • Sound texture — zero-crossing rate. High values indicate high-frequency content (e.g. breathing, rustling).
  • Snore band — spectral band power in the 20–300 Hz range. Elevated when snore-like sounds are present.

The Phase history chart scrolls automatically to the right edge as new epochs arrive. Each column is one 30-second epoch. A faint pink overlay on a column means a snore event was recorded for that epoch.

Awake
Light sleep
Deep sleep
Snore overlay

Stopping a session

Tap the red Stop Tracking button at the bottom of the active screen. You can also stop from the persistent notification by tapping Stop.

The app immediately finalises the last epoch, closes the foreground service, and navigates to the Session screen where you can review your night.

Crash recovery
If the app or phone crashes mid-session, the foreground service writes a new epoch to the database every 30 seconds. You will lose at most the current unfinished epoch (up to 30 s). The session will be shown as unclosed on the home screen until you tap it to review.

Your results

Session screen

After stopping, DeltaSleep shows three headline numbers at the top:

7h 22m
Sleep time
8%
Snore
34%
Deep sleep
  • Sleep time — total session duration from start to stop.
  • Snore % — percentage of epochs in which snoring was detected.
  • Deep % — percentage of epochs classified as deep sleep.

Reading the hypnogram

The hypnogram is a horizontal bar chart where the x-axis is clock time and colour represents the detected sleep stage. Time labels are shown below the chart every five minutes.

Awake (red)
Light sleep (blue)
Deep sleep (dark blue)
Snore (pink overlay)

The chart scrolls horizontally for long sessions. Pinch-to-zoom is not yet supported — pan by swiping left and right.

How phases are detected
Version 0.1 uses movement and audio heuristics — not a wearable or EEG. The algorithm analyses RMS energy, zero-crossing rate, and spectral band power to infer whether you are awake, in light sleep, or in deep sleep. REM detection is planned for v0.2.

Sleep stats

The three stat cards are computed entirely on-device from the epoch data stored in the local SQLite database. No server calculation, no sync required.

Feel rating

Below the hypnogram, tap a number from 1 (terrible) to 5 (great) to record how rested you felt. This is stored with the session and included in CSV exports so you can correlate subjective quality with objective sleep data over time.

Data & export

Export CSV

Tap Export CSV on the session screen. Android's system file picker opens, letting you choose any folder — Downloads, a USB drive, a cloud folder you have mounted locally — wherever you want the file.

The exported file is named deltasleep_<session_id>.csv and contains one row per 30-second epoch:

CSV columns
timestampUnix ms — epoch start time
phaseAWAKE · LIGHT · DEEP
has_snoretrue · false
rms_energyNormalised 0.0–1.0 audio level
zcrZero-crossing rate (sound texture)
band_powerSpectral energy in 20–300 Hz band

The format is plain UTF-8 CSV with a header row. It opens in Excel, Google Sheets, R, Python pandas, or any other tool you prefer. DeltaSleep never owns your data — once exported, the file is yours.

Analysis ideas
Plot band_power vs time to see snore patterns. Compare deep % across nights against your feel rating. Use the open format to build your own dashboard — that is exactly what it is designed for.

Delete all data

Scroll to the bottom of the home screen and tap Delete all data. A confirmation dialog appears. Tapping Delete will:

  1. Overwrite every byte of the SQLite database file with zeros.
  2. Delete the now-blank database file.
  3. Clear all session and epoch records from the app's UI.
Irreversible
This cannot be undone. Export any sessions you want to keep before deleting.

Individual sessions cannot currently be deleted without deleting all data. Per-session deletion is planned for v0.2.

Data retention

DeltaSleep currently keeps all sessions indefinitely until you manually delete them. Configurable auto-retention (30 / 90 / 365 days) is planned for a future release.

Tips & troubleshooting

Phone placement

The microphone is typically located at the bottom edge of the phone. For best results:

  • On the mattress: Place the phone face-down near your pillow. The mic picks up mattress vibrations and breathing sounds clearly.
  • Nightstand: Works well if within 50–80 cm (20–30 inches). Accuracy decreases beyond 1 m.
  • Avoid covering the mic: Do not put the phone under a pillow — muffled audio will reduce phase detection accuracy.
  • Case matters: Thick silicone cases covering the bottom mic port reduce sensitivity. Remove the case or flip it so the mic is uncovered.

Battery usage

DeltaSleep targets ≤ 3% battery drain per 8-hour night. The mic duty-cycles — it sleeps for ~20% of each analysis window when no events are detected, reducing CPU and radio wake-ups.

  • Keep the phone plugged in overnight if possible — the charging cable also keeps the phone from moving, which reduces false-positive movement events.
  • Enable Do Not Disturb before sleeping. Incoming calls and notifications do not interrupt tracking, but screen-on events from notifications consume battery.
  • If your phone's battery optimisation kills the foreground service, go to Settings → Apps → DeltaSleep → Battery and set it to Unrestricted.
Battery optimisation
Aggressive battery optimisation (common on Xiaomi, Huawei, OnePlus, and Samsung with "Adaptive Battery") can terminate foreground services. If tracking stops unexpectedly, check your manufacturer's background-app management settings and whitelist DeltaSleep.

Music, podcasts & white noise

DeltaSleep uses Android's AUDIOFOCUS_GAIN_TRANSIENT_MAY_DUCK strategy combined with the mix-with-others audio session, so it does not request exclusive microphone ownership. Spotify, Audible, YouTube Music, white-noise apps, and sleep-sound apps all continue playing normally while tracking is active.

The DSP pipeline includes a voice-activity detector (VAD) tuned to distinguish human speech and snoring from music and spoken-word content. If you play audio with heavy bass (e.g. binaural beats in the 20–300 Hz range), snore detection accuracy may decrease — consider raising the snore sensitivity threshold when listening to such content.

Frequently asked questions

Why does the first epoch always show Awake?
The classifier needs a calibration window to establish the ambient noise baseline. The first epoch (first 30 seconds) is intentionally marked Awake because there is not yet enough data to distinguish silence from low-activity sleep. This is expected behaviour.
The app shows I was snoring but my partner says I wasn't.
Snore detection uses band-power analysis in the 20–300 Hz range. Some environmental sounds — fans, HVAC systems, traffic — fall in the same band. If you are getting false positives, note the time of events on your hypnogram and compare them with any background noise patterns in your room. A dedicated settings screen with adjustable snore sensitivity is coming in v0.2.
Tracking stopped in the middle of the night. What happened?
The most common cause is Android battery optimisation killing the foreground service. Go to Settings → Apps → DeltaSleep → Battery and select Unrestricted (or equivalent for your phone). Samsung devices call it "Allow background activity"; Xiaomi devices call it "No restrictions".
Does DeltaSleep work without granting the notification permission?
Yes — tracking still works. However, Android 13+ requires a visible foreground-service notification to keep background processes alive. Without notification permission, the service may be terminated by the OS more aggressively. Granting notifications is strongly recommended for reliable overnight tracking.
Can I use DeltaSleep alongside a smartwatch or fitness tracker?
Yes. DeltaSleep is completely independent of wearables and does not communicate with any Bluetooth or third-party device. Both can run simultaneously — they will simply produce separate, independent records.
Is my audio ever saved to a file?
No. Raw PCM audio is processed in memory in 10 ms frames and discarded immediately. Only the computed feature values (RMS, ZCR, band power) for each 30-second epoch are written to the local database. Audio files are never created by default. An optional "save snore clips" setting (max 10 s per clip, auto-purged) is planned for a future release and will be opt-in only.
Where is the database stored?
The SQLite database lives in the app's private data directory (/data/data/io.github.ntufar.deltasleep/databases/). It is not accessible to other apps or visible in the system file picker. Uninstalling the app removes it.
How do I report a bug?
Open an issue on GitHub. Include your Android version, phone model, and a description of what happened. No logs or audio are collected automatically, so the more detail you provide the better.