docs: update README with project description, features, build instructions, usage, and sound pack details
This commit is contained in:
1 file changed
+154
-46
@@ -1,21 +1,24 @@
|
||||
<div align="center">
|
||||
<img src="assets/sample-logo-470x235.png" alt="Project Logo">
|
||||
|
||||
# Project Name
|
||||
# KeyVibe
|
||||
|
||||
> A modern, elegant solution for [brief description]
|
||||
> A C-based CLI tool that brings realistic mechanical keyboard sounds to every keystroke.
|
||||
|
||||
KeyVibe listens to your keyboard events and plays high‑quality switch sounds with low latency. It ships with multiple sound packs and supports your own custom packs. Run it interactively or as a background daemon with live reload of your preferences.
|
||||
|
||||
</div>
|
||||
|
||||
<div align="center">
|
||||
|
||||
[](https://github.com/your-username/your-repo/graphs/contributors)
|
||||
[](https://github.com/your-username/your-repo/stargazers)
|
||||
[](https://github.com/your-username/your-repo/network/members)
|
||||
[](LICENSE)
|
||||
[](https://github.com/your-username/your-repo/issues)
|
||||
[](https://github.com/your-username/your-repo/pulse)
|
||||
[**Documentation**](https://your-project-docs.com) • [**Demo**](https://your-demo-link.com) • [**Report Bug**](https://github.com/your-username/your-repo/issues) • [**Request Feature**](https://github.com/your-username/your-repo/discussions)
|
||||
[](https://github.com/S4NKALP/KeyVibe/graphs/contributors)
|
||||
[](https://github.com/S4NKALP/KeyVibe/stargazers)
|
||||
[](https://github.com/S4NKALP/KeyVibe/network/members)
|
||||
[](LICENSE)
|
||||
[](https://github.com/S4NKALP/KeyVibe/issues)
|
||||
[](https://github.com/S4NKALP/KeyVibe/pulse)
|
||||
|
||||
[**Report Bug**](https://github.com/S4NKALP/KeyVibe/issues) • [**Request Feature**](https://github.com/S4NKALP/KeyVibe/discussions)
|
||||
|
||||
</div>
|
||||
|
||||
@@ -23,51 +26,156 @@
|
||||
|
||||
## ✨ Features
|
||||
|
||||
## 🚀 Quick Start
|
||||
- Real-time key press/release sound playback
|
||||
- Multiple bundled sound packs
|
||||
- User sound packs under `~/.local/share/keyvibe/audio/`
|
||||
- Background daemon mode with PID file and safe shutdown
|
||||
- Live config reload on `~/.keyvibe.json` changes (daemon mode)
|
||||
|
||||
## 📋 Prerequisites
|
||||
## 📋 Dependencies
|
||||
|
||||
## 🛠️ Installation
|
||||
- build-essential
|
||||
- pkg-config
|
||||
- libjson-c-dev
|
||||
- libpulse-dev
|
||||
- libsndfile1-dev
|
||||
- libinput-dev
|
||||
- libevdev-dev
|
||||
- libudev-d
|
||||
|
||||
## 🛠️ Build
|
||||
|
||||
```bash
|
||||
make -j$(nproc)
|
||||
sudo make install
|
||||
```
|
||||
|
||||
## 💡 Usage
|
||||
|
||||
## 🏗️ Project Structure
|
||||
```bash
|
||||
./keyvibe --list # List available sound packs (system + user)
|
||||
|
||||
./keyvibe # Run with defaults
|
||||
|
||||
./keyvibe -c -s `sound_pack` -V 60 # Select pack and volume, override persisted config for this run
|
||||
|
||||
./keyvibe --daemon # Background daemon mode
|
||||
|
||||
./keyvibe --stop # Stop daemon
|
||||
|
||||
```
|
||||
|
||||
> config file will be create at `$HOME` as `.keyvibe.json`
|
||||
|
||||
```
|
||||
|
||||
Flags:
|
||||
|
||||
- `-s, --sound <name>`: sound pack name
|
||||
- `-V, --volume <0-100>`: volume percent
|
||||
- `-c, --override-config`: use CLI values for this run
|
||||
- `-l, --list`: list sound packs
|
||||
- `--daemon | --stop | --reload`
|
||||
- `-v, --verbose`
|
||||
```
|
||||
|
||||
## 🎵 Sound Packs
|
||||
|
||||
System packs are installed under: `/usr/share/keyvibe/audio/`
|
||||
|
||||
User packs go under: `~/.local/share/keyvibe/audio/<pack-name>/`
|
||||
|
||||
Required files inside each `<pack-name>/` directory:
|
||||
|
||||
- `config.json` (format matches bundled packs)
|
||||
- Audio files referenced by `config.json`
|
||||
|
||||
Resolution order when selecting `-s <name>`:
|
||||
|
||||
1. `~/.local/share/keyvibe/audio/<name>/`
|
||||
2. `/usr/share/keyvibe/audio/<name>/`
|
||||
|
||||
List shows `(user)` or `(system)` source next to each pack.
|
||||
|
||||
### config.json structure (custom packs)
|
||||
|
||||
KeyVibe supports two modes via `key_define_type`: `single` and `multi`.
|
||||
|
||||
- `single`: one long audio file; per-key plays a segment `[start_ms, duration_ms]`.
|
||||
- `multi`: separate audio files; per-key maps to its own press/release files; also supports a set of generic press sounds and a generic release.
|
||||
|
||||
Minimal schemas and examples:
|
||||
|
||||
```json
|
||||
// Single mode (one audio file, sliced by key)
|
||||
{
|
||||
"key_define_type": "single",
|
||||
"sound": "purple.ogg", // relative to the pack dir
|
||||
"defines": {
|
||||
"30": [120, 80], // key_code 30: start_ms=120, duration_ms=80
|
||||
"48": [300, 100]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```json
|
||||
// Multi mode (separate files, optional generic patterns)
|
||||
{
|
||||
"key_define_type": "multi",
|
||||
// Generic press sound(s): can be one file, a printf-like pattern, or a {0-4} pattern
|
||||
// Examples:
|
||||
// "GENERIC.mp3"
|
||||
// "GENERIC_R%d.mp3" // expands R0..R4 if files exist
|
||||
// "GENERIC_R{0-4}.mp3" // also expands to R0..R4
|
||||
"sound": "GENERIC_R{0-4}.mp3",
|
||||
|
||||
// Optional generic release sound
|
||||
"soundup": "release/GENERIC.mp3",
|
||||
|
||||
// Per-key overrides (key codes from libinput/libevdev)
|
||||
// For release-specific files, append "-up" to the key code string
|
||||
"defines": {
|
||||
"57": "press/SPACE.mp3", // SPACE press
|
||||
"57-up": "release/SPACE.mp3", // SPACE release
|
||||
"28": "press/ENTER.mp3",
|
||||
"14": "press/BACKSPACE.mp3"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Notes:
|
||||
|
||||
- All paths in `config.json` are relative to the sound pack directory.
|
||||
- In multi mode, if a key press isn’t mapped, a random generic press file is chosen if provided.
|
||||
- In multi mode, if a key release isn’t mapped, `soundup` is used if provided.
|
||||
- In single mode, only presses are played; releases are ignored.
|
||||
|
||||
## Available Sound Packs:
|
||||
|
||||
- nk-cream
|
||||
- cherrymx-black-abs
|
||||
- cherrymx-red-pbt
|
||||
- cherrymx-blue-abs
|
||||
- eg-oreo
|
||||
- cherrymx-brown-pbt
|
||||
- eg-crystal-purple
|
||||
- cherrymx-brown-abs
|
||||
- topre-purple-hybrid-pbt
|
||||
- cream-travel
|
||||
- holy-pandas
|
||||
- mxbrown-travel
|
||||
- cherrymx-red-abs
|
||||
- mxblack-travel
|
||||
- cherrymx-black-pbt
|
||||
- turquoise
|
||||
- cherrymx-blue-pbt
|
||||
- mxblue-travel
|
||||
- banana-split-lubed
|
||||
|
||||
## 🤝 Contributing
|
||||
|
||||
We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
|
||||
|
||||
### Development Setup
|
||||
|
||||
1. Fork the repository
|
||||
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
|
||||
3. Commit your changes (`git commit -m 'Add amazing feature'`)
|
||||
4. Push to the branch (`git push origin feature/amazing-feature`)
|
||||
5. Open a Pull Request
|
||||
PRs welcome. Please keep code modular and readable, and prefer small, focused changes.
|
||||
|
||||
## 📄 License
|
||||
|
||||
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
|
||||
|
||||
## 🙏 Acknowledgments
|
||||
|
||||
- Thanks to all [contributors](https://github.com/your-username/your-repo/graphs/contributors)
|
||||
- Built with [technology-stack](https://technology-website.com)
|
||||
|
||||
---
|
||||
|
||||
To use this template, follow these steps:
|
||||
|
||||
1. [Fork the repository](https://github.com/S4NKALP/README-Templates/fork)
|
||||
2. Clone the forked repository to your local environment
|
||||
3. Make the necessary changes and modifications.
|
||||
4. Commit and push your changes.
|
||||
5. Create a pull repository to the original repository.
|
||||
|
||||
<div align="center">
|
||||
|
||||
**[⬆ Back to Top](#project-name)**
|
||||
|
||||
Made with ❤️ by [Your Name](https://github.com/your-username)
|
||||
|
||||
</div>
|
||||
MIT — see [LICENSE](LICENSE).
|
||||
Reference in new issue
Block a user