INSTALLATION.md

Installation Guide

This document covers the full setup process for running Floura locally, including dependencies, environment variables, and the Piper text-to-speech voice model.

Prerequisites

• Python 3.9 or later
• pip
• A Replicate API key (see REPLICATE.md)

1. Clone the Repository

git clone <repository-url>
cd Floura

2. Create a Virtual Environment

python -m venv venv
source venv/bin/activate

On Windows (Git Bash):

python -m venv venv
source venv/Scripts/activate

3. Install Dependencies

pip install -r requirements.txt --break-system-packages

4. Configure Environment Variables

Copy the example environment file and fill in your credentials:

cp .env.example .env

Edit .env and set:

REPLICATE_API_KEY=your_api_key_here
AI_MODEL=meta/llama-2-70b-chat

See REPLICATE.md for instructions on obtaining an API key.

5. Download the Voice Model

Floura uses Piper TTS with the en_GB-semaine-medium voice. Download the model and its configuration file into src/data/voices:

mkdir -p src/data/voices

curl -L -o src/data/voices/en_GB-semaine-medium.onnx https://huggingface.co/rhasspy/piper-voices/resolve/main/en/en_GB/semaine/medium/en_GB-semaine-medium.onnx

curl -L -o src/data/voices/en_GB-semaine-medium.onnx.json https://huggingface.co/rhasspy/piper-voices/resolve/main/en/en_GB/semaine/medium/en_GB-semaine-medium.onnx.json

Additional Piper voices can be browsed at the Piper TTS voice samples page.

6. Verify Installation

Confirm the required Python packages are importable:

python -c "import piper; print('piper OK')"
python -c "import sounddevice; print('sounddevice OK')"
python -c "import soundfile; print('soundfile OK')"

7. Verify the Voice Model Loads

mkdir -p src/data/audio
echo "hello world" | piper -m src/data/voices/en_GB-semaine-medium.onnx -f src/data/audio/test.wav

If a test.wav file is created in src/data/audio, the voice model is installed correctly.

8. Run the Application

python src/main.py