Gate Pulse

Gate Pulse is an offline Android app for analyzing long audio recordings and surfacing acoustically unusual periods. It is designed for personal or internal review workflows such as checking unattended environmental recordings for notable sounds.

The app runs fully on-device. Audio is selected through Android's system file picker, decoded locally, analyzed locally, and stored in app-private storage.

Features

• Offline audio analysis with no cloud processing
• Native Android app built with Kotlin and Jetpack Compose
• Long-running analysis through WorkManager foreground work
• Local metadata storage with Room
• App settings with DataStore
• Generated reports with event metadata, CSV outputs, and playable WAV clips
• English and Vietnamese UI strings
• Light, dark, and system theme modes

Supported Audio Formats

Gate Pulse v1 explicitly supports common Android-decodable audio formats:

• .mp3
• .m4a
• .wav
• .aac

Large recordings are processed through an on-disk PCM cache instead of loading the full decoded file into memory.

What Gate Pulse Is For

Gate Pulse is an acoustic triage tool. It can help you review long recordings by extracting the most unusual sound events, such as knocks, impacts, mechanical sounds, sustained activity, or sudden ambient changes.

It is not a security system, speech recognizer, forensic tool, or guarantee that a specific event did or did not happen. Treat results as review aids that still require human listening.

Project Structure

app/                         Android application
app/src/main/java/.../analysis/  Kotlin audio analysis pipeline
app/src/main/java/.../data/      Room entities/DAOs and DataStore settings
app/src/main/java/.../worker/    WorkManager foreground analysis worker
app/src/main/res/                Android resources and localization strings
docs/                        Maintainer and release notes

See docs/ARCHITECTURE.md for a self-contained technical description of the Android implementation and analysis algorithm.

Requirements

• JDK 17
• Android SDK
• Android Gradle Plugin dependencies from Google/Maven Central
• Android 10 or newer recommended

The project uses the Gradle wrapper, so a local Gradle installation is not required.

Build A Debug APK

./gradlew assembleDebug

The APK is written to:

app/build/outputs/apk/debug/app-debug.apk

Install it on a connected device:

adb install -r app/build/outputs/apk/debug/app-debug.apk

Run Tests

./gradlew testDebugUnitTest

Current JVM tests cover timecode formatting, robust statistics, feature extraction, and label text.

App Workflow

1. Open Gate Pulse.
2. Choose New Analysis.
3. Select an audio file through Android's system file picker.
4. Let the foreground analysis run.
5. Review results on the Analyses page.
6. Open an analysis to view the Audio Activity Report.
7. Play individual clips or play all clips sequentially.

Generated files are stored under app-private storage:

filesDir/analyses/<analysis-id>/

Each completed analysis may include:

• report.json
• features.csv
• scores.csv
• clips/*.wav
• cache/decoded_s16le_16k_mono.pcm

Deleting an analysis removes generated app files and metadata. It does not delete the original source audio file.

Important Settings

Default analysis settings are intentionally conservative:

• Window: 1.0 second
• Hop: 0.5 seconds
• Merge gap: 3.0 seconds
• Minimum event duration: 0.5 seconds
• Pre-roll: 2.0 seconds
• Post-roll: 3.0 seconds
• Top N: 50
• Threshold: auto

Top N is the maximum number of ranked events/clips kept in the report. Larger values include weaker events and may create more noise to review.

Privacy

See PRIVACY.md. In short: Gate Pulse is designed to run offline, and audio analysis happens on the device.

Release Status

Current version: 1.0.0

This repository is prepared for sideloaded/internal debug builds. Before a public Play Store release, add production signing configuration, final launcher artwork, Play Store privacy text, broader device testing, and backup exclusions for generated analysis artifacts.

See docs/RELEASE_CHECKLIST.md.

License

MIT. See LICENSE.