{"id":31639995,"url":"https://github.com/jonaylor89/ush","last_synced_at":"2025-10-07T02:08:57.644Z","repository":{"id":310402783,"uuid":"1039613310","full_name":"jonaylor89/ush","owner":"jonaylor89","description":"communicate between devices using ultrasonic sound waves","archived":false,"fork":false,"pushed_at":"2025-08-19T03:54:39.000Z","size":140,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-16T13:17:49.596Z","etag":null,"topics":["airgap","audio","fft","fsk","rust","ultrasonic"],"latest_commit_sha":null,"homepage":"https://crates.io/crates/ush","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jonaylor89.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-08-17T16:04:35.000Z","updated_at":"2025-08-18T04:38:02.000Z","dependencies_parsed_at":"2025-08-17T22:23:57.074Z","dependency_job_id":"8595f44f-48a4-451d-957f-76fc08969d15","html_url":"https://github.com/jonaylor89/ush","commit_stats":null,"previous_names":["jonaylor89/ush"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/jonaylor89/ush","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonaylor89%2Fush","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonaylor89%2Fush/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonaylor89%2Fush/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonaylor89%2Fush/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jonaylor89","download_url":"https://codeload.github.com/jonaylor89/ush/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonaylor89%2Fush/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278708004,"owners_count":26031932,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-07T02:00:06.786Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["airgap","audio","fft","fsk","rust","ultrasonic"],"created_at":"2025-10-07T02:08:37.382Z","updated_at":"2025-10-07T02:08:57.639Z","avatar_url":"https://github.com/jonaylor89.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ush - Ultrasonic Shell\n\n**ush** (ultrasonic shell) is a terminal program that enables communication between devices using ultrasonic sound waves. Send text messages, engage in real-time chat, or transfer files using audio frequencies above human hearing range (18-22 kHz).\n\n## Features\n\n- **Text Messaging**: Send and receive text messages via ultrasonic audio\n- **Interactive Chat**: Real-time chat mode for back-and-forth conversations\n- **File Transfer**: Send files by breaking them into audio packets\n- **Cross-Platform**: Works on macOS, Linux, and Windows\n- **Robust Protocol**: Built-in error detection with CRC checksums\n- **Noise Filtering**: Signal processing to handle noisy environments\n- **Audio Recording**: Save/load transmissions as WAV files for debugging\n\n## Quick Start\n\n### Installation\n\n```bash\ncargo instal ush\n```\n\n### Basic Usage\n\n**Send a message** (Device A):\n```bash\nush send \"Hello, World!\"\n```\n\n**Listen for messages** (Device B):\n```bash\nush listen\n```\n\n### Requirements\n\n- **Audio devices**: Working microphone and speakers/headphones\n- **Rust**: 1.70+ (2021 edition)\n- **Operating System**: macOS, Linux, or Windows\n\n## Usage Examples\n\n### Basic Communication\n\nSend a simple message:\n```bash\nush send \"Hello from device A!\"\n```\n\nListen with a 30-second timeout:\n```bash\nush listen --timeout 30\n```\n\nSend message multiple times for reliability:\n```bash\nush send \"Important message\" --repeat 3\n```\n\n### Interactive Chat Mode\n\nStart a chat session:\n```bash\nush chat --username alice\n```\n\nChat with automatic acknowledgments:\n```bash\nush chat --username bob --ack\n```\n\n### File Transfer\n\nSend a small file:\n```bash\nush send-file document.txt\n```\n\nSend with custom chunk size and delay:\n```bash\nush send-file image.jpg --chunk-size 32 --delay 1000\n```\n\nReceive a file:\n```bash\nush receive-file downloaded.txt --timeout 300\n```\n\n### Audio Debugging\n\nSave transmitted audio for analysis:\n```bash\nush send \"Debug test\" --save-wav output.wav\n```\n\nProcess audio from a file instead of live:\n```bash\nush listen --from-wav recorded.wav\n```\n\n### Testing and Diagnostics\n\nTest the complete encoding/decoding pipeline:\n```bash\nush test loopback \"Test message\"\n```\n\nList available audio devices:\n```bash\nush test devices\n```\n\nGenerate a test tone:\n```bash\nush test generate 19000 --duration 2.0\n```\n\nMeasure background noise:\n```bash\nush test noise --duration 5\n```\n\n### Debug Mode and Analysis\n\nAudio analysis with spectrograms and FFT visualizations:\n\n```bash\n# Debug analysis of live audio capture\nush listen --timeout 30 --debug --debug-output ./debug_analysis\n\n# Debug analysis of existing WAV file\nush listen --from-wav recording.wav --debug --debug-output ./analysis\n\n# Quick debug loopback test\njust debug-loopback \"Test message\"\n\n# Comprehensive debug demonstration\njust debug-demo\n```\n\nDebug mode generates:\n- **Spectrograms**: Time-frequency heatmaps showing FSK signal patterns\n- **FFT Analysis**: Frequency domain plots with signal quality metrics\n- **Signal Metrics**: SNR estimation, dynamic range, frequency presence\n- **HTML Reports**: Interactive analysis with interpretation guides\n- **Raw Audio**: Complete recordings for external analysis\n\n### Advanced Options\n\nUse custom frequencies:\n```bash\nush --freq-0 17000 --freq-1 21000 send \"Custom frequencies\"\n```\n\nApply noise filtering:\n```bash\nush listen --filter --threshold 0.2\n```\n\nVerbose logging:\n```bash\nush --verbose send \"Debug message\"\n```\n\n## Configuration\n\n### Audio Settings\n\n- `--sample-rate`: Audio sample rate (default: 44100 Hz)\n- `--freq-0`: Frequency for bit '0' (default: 18000 Hz)\n- `--freq-1`: Frequency for bit '1' (default: 20000 Hz)\n\n### Protocol Settings\n\nThe protocol uses:\n- **Modulation**: FSK (Frequency Shift Keying)\n- **Symbol Duration**: 10ms per bit\n- **Error Detection**: CRC-32 checksums\n- **Framing**: Preamble + start/end delimiters\n\n### Performance\n\nTypical performance characteristics:\n- **Data rate**: ~50-100 characters per second\n- **Frequency range**: 18-22 kHz (above human hearing)\n- **Detection range**: 2-10 meters (depending on environment)\n- **Latency**: ~100-500ms end-to-end\n\n## Troubleshooting\n\n### Common Issues\n\n**\"No audio device found\"**\n- Ensure microphone/speakers are connected and working\n- Check system audio permissions\n- Try `ush test devices` to list available devices\n\n**\"Failed to decode message\"**\n- Increase volume on sending device\n- Reduce background noise\n- Use `--filter` option for noisy environments\n- Try `--repeat 3` to send message multiple times\n\n**\"Timeout waiting for signal\"**\n- Check that devices are within range (~2-10 meters)\n- Ensure audio frequencies aren't blocked by speaker/mic limitations\n- Verify both devices are using same frequency settings\n\n### Audio Quality Tips\n\n1. **Environment**: Use in quiet environments when possible\n2. **Distance**: Keep devices 2-10 meters apart for best results\n3. **Volume**: Set speaker volume to 50-80% (not maximum)\n4. **Hardware**: Use external speakers/microphones for better range\n5. **Interference**: Avoid other ultrasonic sources (some motion sensors, etc.)\n\n### Debug Mode\n\nMonitor live audio for debugging:\n```bash\nush debug --spectrum --waveform --rate 20\n```\n\n### Performance Testing\n\nRun comprehensive tests:\n```bash\ncargo test --release\n```\n\nBenchmark encoding/decoding speed:\n```bash\ncargo test --release test_performance_benchmarks -- --nocapture\n```\n\n## Architecture\n\n### Module Structure\n\n```\nsrc/\n├── main.rs          # CLI entry point and command routing\n├── lib.rs           # Library exports and module declarations\n├── app.rs           # Main application logic and coordination\n├── cli.rs           # Command-line interface definitions\n├── audio.rs         # Cross-platform audio I/O with cpal\n├── modulation.rs    # FSK encoding/decoding with FFT\n├── protocol.rs      # Message framing and error detection\n└── error.rs         # Centralized error handling\n```\n\n### Key Dependencies\n\n- **cpal**: Cross-platform audio I/O\n- **rustfft**: Fast Fourier Transform for demodulation\n- **hound**: WAV file reading/writing\n- **clap**: Command-line argument parsing\n- **tokio**: Async runtime for non-blocking I/O\n- **crc**: CRC checksum calculation\n\n### Protocol Stack\n\n```\nApplication Layer    │ Text messages, files, chat\nProtocol Layer       │ Framing, sequencing, CRC checksums\nModulation Layer     │ FSK (Frequency Shift Keying)\nPhysical Layer       │ Ultrasonic audio (18-22 kHz)\n```\n\n## Building from Source\n\n### Prerequisites\n\n```bash\n# Install Rust toolchain\ncurl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh\n\n# Install system dependencies (Linux only)\n# Ubuntu/Debian:\nsudo apt-get install libasound2-dev pkg-config\n\n# CentOS/RHEL:\nsudo yum install alsa-lib-devel pkgconfig\n```\n\n### Build Commands\n\n```bash\n# Debug build\ncargo build\n\n# Release build (optimized)\ncargo build --release\n\n# Run tests\ncargo test\n\n# Run with logging\nRUST_LOG=debug cargo run -- send \"test\"\n\n# Generate documentation\ncargo doc --open\n```\n\n### Cross-Compilation\n\nBuild for different platforms:\n```bash\n# Add targets\nrustup target add x86_64-pc-windows-gnu\nrustup target add x86_64-apple-darwin\n\n# Cross-compile\ncargo build --target x86_64-pc-windows-gnu --release\n```\n\n## Development\n\n### Running Tests\n\n```bash\n# Unit tests\ncargo test\n\n# Integration tests\ncargo test --test integration_tests\n\n# Specific test\ncargo test test_full_pipeline\n\n# With output\ncargo test -- --nocapture\n```\n\n### Adding New Features\n\n1. **Fork the repository**\n2. **Create a feature branch**\n3. **Write tests first** (TDD approach)\n4. **Implement the feature**\n5. **Run full test suite**\n6. **Submit a pull request**\n\n### Code Style\n\n- Use `cargo fmt` for formatting\n- Use `cargo clippy` for linting\n- Follow Rust naming conventions\n- Add documentation for public APIs\n- Include tests for new functionality\n\n## FAQ\n\n**Q: Why ultrasonic frequencies?**\nA: Ultrasonic frequencies (18-22 kHz) are above human hearing range, so communication doesn't create audible noise. Most computer speakers and microphones support these frequencies.\n\n**Q: What's the maximum range?**\nA: Typically 2-10 meters depending on environment, speaker/microphone quality, and background noise. Outdoor range may be longer.\n\n**Q: Can I use this through walls?**\nA: Sound waves don't penetrate walls well. ush is designed for same-room or adjacent room communication.\n\n**Q: Is this secure?**\nA: Currently no encryption is implemented. Messages are transmitted as plaintext audio. Anyone with a microphone in range can receive messages.\n\n**Q: Why is it slow compared to WiFi/Bluetooth?**\nA: Audio-based communication is inherently slower due to symbol duration and error correction needs. It's designed for short messages, not bulk data transfer.\n\n**Q: Does this work on mobile devices?**\nA: The current implementation is desktop-focused. Mobile support would require platform-specific audio handling.\n\n## Contributing\n\nContributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\nAreas where help is needed:\n- Mobile platform support\n- GUI interface\n- Improved noise filtering\n- Encryption/security features\n- Performance optimizations\n- Additional modulation schemes\n\n## License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n## Credits\n\nBuilt with:\n- [cpal](https://github.com/RustAudio/cpal) for cross-platform audio\n- [rustfft](https://github.com/ejmahler/RustFFT) for signal processing\n- [clap](https://github.com/clap-rs/clap) for CLI parsing\n\nInspired by projects like:\n- Acoustic data transmission protocols\n- Ham radio digital modes\n- Ultrasonic communication research\n\n---\n\n**Note**: This is experimental software. Use responsibly and be mindful\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjonaylor89%2Fush","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjonaylor89%2Fush","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjonaylor89%2Fush/lists"}