feat: Initial release of v0.0.4-alpha

Initial clean release of the Vosk command-line dictation tool. This version is prepared for public release and includes the required directory structure.

Author: RonanDavalan

.gitignore

@@ -0,0 +1,48 @@
+# Fichiers compilés
+*.o
+*.out
+
+# Dossiers
+node_modules/
+dist/
+page-html/*
+
+
+# Python
+__pycache__/
+*.pyc
+
+vosk-env/
+*.pyo
+*.pyd
+.Python
+env/
+venv/
+
+# Fichiers de configuration locaux
+config.local.json
+
+# Fichiers temporaires
+*.tmp
+*.log
+GEMINI.md
+# Environnements virtuels Python
+vosk-env/
+venv/
+
+# Fichiers de cache et temporaires Python
+__pycache__/
+*.py[co]
+*.pyd
+
+# Fichiers IDE et système
+.idea/
+.vscode/
+.DS_Store
+Thumbs.db
+
+# Ignorer TOUT le contenu du dossier des modèles...
+vosk-model/*
+
+# ...MAIS faire une exception pour conserver le fichier .gitkeep.
+!vosk-model/.gitkeep

CONTRIBUTING.md

@@ -0,0 +1,64 @@
+# Contribution Guide
+
+A huge thank you for your interest in this project! Every contribution, whether it's an idea, a bug report, or a few lines of code, is valuable and welcome.
+
+## Project Philosophy: A Modern Partnership
+
+This project was born from a unique partnership: it was **architected and driven by a human**, but its execution was greatly accelerated by the **power of several Large Language Models (LLMs)** like Claude, Gemini, and others.
+
+We see this not as mere assistance, but as a modern development model where human vision guides the efficiency of AI. We encourage contributions that share this spirit of innovation, experimentation, and effectiveness.
+
+## How You Can Help
+
+All help is welcome. Here are the best ways to get started:
+
+### 🐛 Found a Bug?
+
+1.  **Check First!** Take a look at the [Issues](https://github.com/RonanDavalan/projet_vosk/issues) to make sure the bug hasn't already been reported.
+2.  **Open a New Issue.** If the bug is new, please report it with as much detail as possible:
+    *   Your Linux distribution and version.
+    *   The exact steps to reproduce the problem.
+    *   The full error message, copy-pasted into the issue.
+
+### ✨ Have an Idea for an Improvement?
+
+All suggestions to improve the tool are welcome!
+
+1.  **Open a [new issue](https://github.com/RonanDavalan/projet_vosk/issues) to start the discussion.**
+2.  Describe your idea and explain how it would benefit users.
+
+### 💻 Want to Contribute Code?
+
+Fantastic! Here's how to proceed to ensure your contribution is smoothly integrated.
+
+**1. Prepare Your Environment**
+
+*   **Fork** the repository (create a copy on your own GitHub account).
+*   **Clone** your fork to your machine: `git clone https://github.com/YOUR_USERNAME/YOUR_PROJECT.git`
+*   **Create a new branch** for your changes. This is essential to avoid working directly on `main`.
+    ```bash
+    git checkout -b feature/your-feature-name
+    ```
+
+**2. Code!**
+
+*   Make your changes. Try to keep the code clear, simple, and commented where necessary.
+*   Be sure to test your changes to verify that they work and don't create new bugs.
+
+**3. Submit Your Contribution**
+
+*   **Commit your changes** with a clear message, **in English**. Using English and following a convention is a best practice for maintaining a clean history that is understandable by everyone. We use the "Conventional Commits" standard.
+
+    *   For a new feature: `git commit -m "feat: add voice command for XYZ"`
+    *   For a bug fix: `git commit -m "fix: resolve issue with microphone detection"`
+    *   For documentation: `git commit -m "docs: update installation guide"`
+
+*   **Push your branch** to your fork on GitHub.
+*   **Open a Pull Request (PR)** from your fork to the main project's `main` branch. In the PR description, explain what you did and why.
+
+## Code Style
+
+The project follows the **PEP 8** style conventions for Python. Clean and readable code is as important as code that works!
+
+---
+Thank you again for your time and help. It's thanks to people like you that open-source projects can grow and improve.

CONTRIBUTORS.md

@@ -0,0 +1,30 @@
+# Acknowledgments and Contributors
+
+This project could not have come to life without the hard work of many people and the existence of fantastic open-source tools. I want to express my deep gratitude to everyone who contributed, directly or indirectly, to its creation.
+
+## Core Projects and Libraries
+
+This software relies entirely on the following open-source projects. A big thank you to their developers and communities for providing such powerful and accessible tools.
+
+*   **[Vosk-API](https://alphacephei.com/vosk/)**: For providing the robust and high-performance offline speech recognition engine that is the heart of this application.
+*   **[Python](https://www.python.org/)**: For a versatile programming language and an incredible community.
+*   **[xdotool](https://github.com/jordansissel/xdotool)**: For the essential tool that allows simulating keyboard input and controlling windows under Linux.
+*   **[pactl (PulseAudio)](https://www.freedesktop.org/wiki/Software/PulseAudio/)**: For the commands to manage the system's audio sources.
+*   **[PyYAML](https://pyyaml.org/)**: For handling YAML configuration files.
+*   **[Pynput](https://pynput.readthedocs.io/en/latest/)**: For managing keyboard and mouse events.
+*   **[PyAudio](https://pypi.org/project/PyAudio/)**: For audio capture.
+
+## Design and Development Support
+
+I also want to thank the entities and individuals who helped me structure my ideas, solve complex problems, and improve the quality of the project.
+
+*   **[Gemini & ChatGPT](https://gemini.google.com/)**: For their assistance as tools for brainstorming, code generation, and debugging. Their ability to provide quick answers and different perspectives has been a valuable accelerator throughout development.
+
+## Code and Documentation Contributors
+
+This section is dedicated to all the people who have contributed directly to the project by submitting relevant pull requests or issues.
+
+*(This section is currently empty, but I hope to see your name here soon!)*
+
+---
+*If you wish to contribute, please see our [contribution guide](./CONTRIBUTING.md).*

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Ronan Davalan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,143 @@
+# Vosk-CLI-Dictation
+
+<p align="center">
+  <a href="https://github.com/RonanDavalan/vosk-cli-dictation/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT"></a>
+  <a href="#"><img src="https://img.shields.io/badge/Version-v0.0.4--alpha-yellow.svg" alt="Version: v0.0.4-alpha"></a>
+  <a href="#"><img src="https://img.shields.io/badge/python-3.11+-blue.svg" alt="Python 3.11+"></a>
+  <a href="#"><img src="https://img.shields.io/badge/OS-Debian_12-D70A53.svg" alt="Tested on Debian 12"></a>
+  <a href="#"><img src="https://img.shields.io/badge/Contributions-Welcome-brightgreen.svg" alt="Contributions Welcome"></a>
+</p>
+
+<p align="center">
+  <a href="https://vosk.davalan.fr/"><strong>➡️ Visit the Official Homepage for a full tour!</strong></a>
+</p>
+
+<p align="center">
+  <img src="assets/images/vosk-cli-dictation_live-demo.gif" alt="Live Demonstration">
+</p>
+
+A powerful and customizable command-line dictation tool for Linux, powered by the Vosk engine. Turn your speech into text directly in your terminal and have it appear in any application.
+
+---
+
+## ✨ Why This Project?
+
+This tool was born from the need for a robust, locally-run dictation system on GNU/Linux that gives the user full control over their data and the software's behavior. Unlike cloud-based solutions, it operates **100% offline**, guaranteeing your privacy.
+
+## 🚀 Key Features
+
+*   **System-Wide Integration:** Dictate into any active application (terminal, browser, code editor, etc.).
+*   **Multi-Language Support:** Works out-of-the-box with **English** and **French**.
+*   **Total Control:** Use global hotkeys, voice commands, and manual controls to manage your dictation.
+*   **Fully Customizable:** Configure UI colors, hotkeys, voice commands, and recognition aliases in a simple `config.yaml` file.
+*   **Full Punctuation:** Dictate a complete range of punctuation with natural voice commands.
+*   **Private and Offline:** Runs entirely on your machine. Your voice data never leaves your computer.
+
+> [!WARNING]
+> 
+> **Compatibility Note: X11 vs. Wayland** This application uses `xdotool` for keyboard simulation, which is primarily designed for the **X11 display server**. While it may **not work natively** on systems running **Wayland** by default (such as recent versions of Fedora or Ubuntu), some compatibility can be achieved through **XWayland**, which provides X11 compatibility layer on Wayland systems. For full compatibility, ensure you have an X11 session, though basic functionality might work under Wayland with XWayland.
+
+## ⚙️ Getting Started
+
+### 1. System Dependencies
+
+This project was developed and tested on **Debian 12 (Bookworm)**. You will need the following packages:
+
+```bash
+sudo apt-get update && sudo apt-get install python3-pip python3-venv portaudio19-dev gettext xdotool pulseaudio-utils
+```
+
+### 2. Project Setup
+
+Clone the repository and create the Python virtual environment.
+
+```bash
+git clone https://github.com/RonanDavalan/vosk-cli-dictation.git
+cd vosk-cli-dictation
+python3 -m venv venv
+source venv/bin/activate
+```
+
+### 3. Install Python Dependencies
+
+Install the required Python packages from the `requirements.txt` file.
+
+```bash
+pip install -r requirements.txt
+```
+
+### 4. Download Language Models
+
+This project requires Vosk language models to function. They are not included in the repository and must be downloaded manually.
+
+1.  **Download the models you need:** We recommend starting with the small models for efficiency.
+    *   **French Model:** [vosk-model-small-fr-0.22](https://alphacephei.com/vosk/models/vosk-model-small-fr-0.22.zip)
+    *   **English Model:** [vosk-model-small-en-us-0.15](https://alphacephei.com/vosk/models/vosk-model-small-en-us-0.15.zip)
+
+2.  **Unzip and place them correctly:** After unzipping, the model folders (e.g., `vosk-model-small-fr-0.22`) must be placed directly inside the `vosk-model/` directory of the project.
+
+### 5. Launch The Application
+
+With the virtual environment still active, run the main script.
+
+```bash
+# To run with the French model (default in config)
+python3 src/main.py
+
+# To explicitly run with the English model
+python3 src/main.py -l en
+```
+
+### 💡 Pro Tip: Create a Quick-Launch Command (Optional)
+
+For easier access, you can add a function to your shell's configuration file (e.g., `~/.bashrc` or `~/.zshrc`).
+
+1.  Open your configuration file: `nano ~/.bashrc`
+2.  Add the following lines at the end. **Remember to replace `/path/to/your/vosk-cli-dictation` with the actual, absolute path to the project directory.**
+
+    ```bash
+    # Defines a 'vosk' command to launch the dictation script easily.
+    vosk() {
+        # Check if the project directory exists
+        if [ -d "/path/to/your/vosk-cli-dictation" ]; then
+            cd "/path/to/your/vosk-cli-dictation" && \
+            source venv/bin/activate && \
+            python3 src/main.py "$@" && \
+            deactivate
+        else
+            echo "Error: Project directory not found at /path/to/your/vosk-cli-dictation"
+        fi
+    }
+    ```
+
+3.  Apply the changes by running `source ~/.bashrc` or by opening a new terminal.
+4.  You can now launch the application from anywhere by simply typing `vosk` or `vosk -l en`.
+
+## 🛠️ Usage & Configuration
+
+### Language Selection
+
+The language model is chosen based on the following priority:
+
+1.  **Command-Line Flag (Highest Priority):** Use `-l en` or `-l fr` to force a specific language for the session.
+2.  **Default in `config.yaml` (Fallback):** If no flag is used, the `default_model` from `config/config.yaml` is loaded.
+
+### Manual Commands
+
+While the script is running, you can type these commands in its terminal window and press Enter:
+
+*   `/cancel`: Stops the current recording session without outputting text.
+*   `/delete-word`: Deletes the last typed word.
+*   `/nl`: Inserts a new line (simulates pressing the Enter key).
+
+### Customization
+
+All settings can be modified in the `config/config.yaml` file. This includes hotkeys, UI colors, voice commands, and recognition aliases.
+
+## 🤝 Contributing
+
+This project is open source and contributions are highly encouraged! Please check out our **[Contribution Guide](CONTRIBUTING.md)** and feel free to open an issue on the [issues page](https://github.com/RonanDavalan/vosk-cli-dictation/issues).
+
+## 📄 License
+
+This project is licensed under the **MIT License**. See the [LICENSE](LICENSE) file for details.

assets/images/vosk-cli-dictation_live-demo.gif

@@ -0,0 +1,7 @@
+# babel.cfg
+#
+# This configuration file tells Babel which files to scan for translatable strings.
+# We are telling it to look for the gettext function call `_()` in all Python
+# files located inside the 'src' directory.
+
+[python: src/**.py]