---
title: Eclaire
---

Eclaire (hereinafter the "Application") is a real-time speech-to-speech translation web application that captures live audio from a user's microphone, transcribes the speech using Deepgram's API, and translates the transcribed text into a target language.

## 1. User Documentation

This section is for those interacting with a live instance of the Application.

### Getting Started

1. **Initial Setup**: Open the configuration screen and provide your API credentials and language preferences.

2. **Configuration Options**:
   - **Deepgram API Key**: Required for speech-to-text transcription.
   - **Translation Service API Key**: Required for text translation. The application includes a built-in demonstration key in source comments with a 10 requests/minute limit.
   - **Source Language**: Selected from the source-language allow-list defined in the configuration component.
   - **Target Language**: Selected from the language-code mapping list used by the configuration component.

3. **Using the Translation Interface**:
   - Navigate to the Agent page to begin translation.
   - Click "Start" to begin capturing audio from your microphone.
   - Speak clearly into your microphone in the configured source language.
   - The application will display real-time transcription and translations.
   - Click "Finalize" to manually end the current speech segment if needed.
   - Click "Stop" to end the session.

### Features

- **Real-Time Transcription**: Powered by Deepgram's nova-3-general model with automatic punctuation
- **Multi-Language Translation**: Support for 60+ target languages via LibreTranslate
- **Conversation History**: View all transcriptions and translations in a message-based format
- **Connection Status**: Monitor your connection status and any errors
- **Cost Estimation**: Track estimated costs (approximately $0.32/hour)

### Audio Quality Settings

The application automatically enables:
- Echo cancellation
- Noise suppression
- Auto gain control

### Limitations

- Requires a modern browser with microphone access.
- Requires a WebSocket connection for real-time transcription.
- Translation demo key usage is rate limited.

## 2. Technical Documentation

This section is for those interested in running their own instance of the Application.

### Prerequisites

- Node.js (version compatible with Angular 19.1.4)
- pnpm package manager
- Modern web browser with WebRTC support
- Deepgram API key
- LibreTranslate API key (or access to a LibreTranslate instance)

### Installation

1. Clone the repository:
   ```bash
   git clone <repository-url>
   cd eclaire
   ```

2. Install dependencies:
   ```bash
   pnpm install
   ```

3. Start the development server:
   ```bash
   pnpm run dev
   ```

4. Build for production:
   ```bash
   pnpm run build
   ```

### Technology Stack

**Frontend Framework:**
- Angular 19.1.4 with standalone components
- TypeScript 5.7.3
- RxJS 7.8.2 for reactive programming
- Angular Reactive Forms for configuration management

**External APIs:**
- Deepgram WebSocket API (nova-3-general model) for speech-to-text
- LibreTranslate API for text translation

**Audio Processing:**
- Web Audio API for microphone access
- ScriptProcessor for audio stream processing (4096 buffer size)
- 48kHz sample rate, mono channel, Int16 format

### Architecture

#### Components

1. **HomeComponent** (`src/app/home/home.component.ts`)
   - Landing page with navigation links
   - Entry point for users

2. **ConfigComponent** (`src/app/config/config.component.ts`)
   - Configuration interface using reactive forms
   - Manages API keys and language preferences
   - Form validation for required fields
   - Stores configuration in ConfigService

3. **AgentComponent** (`src/app/agent/agent.component.ts`)
   - Main translation interface
   - Manages WebSocket lifecycle
   - Handles microphone capture and audio streaming
   - Displays transcription and translation results
   - Tracks connection status and errors

#### Services

1. **ConfigService** (`src/app/config.service.ts`)
   - In-memory storage for application configuration
   - Provides configuration access across components
   - Stores: API keys, source language, target language

2. **SocketService** (`src/app/socket.service.ts`)
   - Manages WebSocket connection to Deepgram
   - Handles audio streaming in real-time
   - Event-based architecture for message handling
   - Supports keep-alive and finalisation
   - Configuration options:
     - Model: nova-3-general
     - Language: configurable source language
     - Encoding: linear16
     - Sample rate: 48000
     - Channels: 1 (mono)
     - Endpointing: 500ms
     - Features: punctuate

#### Routing

- `/` - Home page
- `/config` - Configuration page
- `/agent` - Translation interface

### API Integration

#### Deepgram API

The application uses Deepgram's WebSocket API for real-time transcription:

```typescript
wss://api.deepgram.com/v1/listen
```

Query parameters:
- `model=nova-3-general`
- `language=<source-language>`
- `encoding=linear16`
- `sample_rate=48000`
- `channels=1`
- `endpointing=500`
- `punctuate=true`

Authentication: Bearer token (API key) in WebSocket URL

#### LibreTranslate API

The application uses the LibreTranslate API for text translation:

```typescript
https://trans.nhcarrigan.com/translate
```

POST request body:
```json
{
  "q": "<text-to-translate>",
  "source": "<source-language-code>",
  "target": "<target-language-code>",
  "api_key": "<api-key>"
}
```

### Development

#### Available Scripts

- `pnpm run dev` - Start development server
- `pnpm run lint` - Run ESLint with zero warnings policy
- `pnpm run build` - Build for production

#### Code Quality

- ESLint configuration from `@nhcarrigan/eslint-config`
- TypeScript configuration from `@nhcarrigan/typescript-config`
- Strict linting with `--max-warnings 0`

#### Testing

- Framework: Jasmine ~5.5.0
- Test Runner: Karma ~6.4.4
- Coverage reporting enabled

### Deployment Considerations

1. **Environment Variables**: API keys should be configurable per deployment environment
2. **CORS**: Ensure proper CORS configuration for LibreTranslate API
3. **HTTPS**: Required for microphone access in production
4. **WebSocket**: Ensure WebSocket connections are allowed through firewalls
5. **Browser Support**: Requires WebRTC and Web Audio API support

### Performance

- Audio streaming at 48kHz with 4096 sample buffer
- WebSocket for low-latency real-time communication
- Estimated cost: $0.32/hour for Deepgram usage
- Efficient audio processing with minimal overhead

## 3. Legal Documentation

This section is for expansions to our legal policies specific to the Application.

### License

This software is licensed under the [global software licence](https://docs.nhcarrigan.com/#/license).

Copyright held by Naomi Carrigan.

### Privacy Policy

The Application's privacy practices are governed by the [global privacy policy](https://docs.nhcarrigan.com/#/privacy).

#### Application-Specific Privacy Considerations

1. **Audio Data**: The Application captures audio from your microphone and streams it to Deepgram's servers for transcription. Audio data is not stored locally by the Application.

2. **API Keys**: API keys are stored in-memory during your session and are not persisted to local storage or transmitted to any servers other than the respective API providers (Deepgram and LibreTranslate).

3. **Third-Party Services**:
   - **Deepgram**: Audio data is transmitted to Deepgram for transcription. Refer to [Deepgram's privacy policy](https://deepgram.com/privacy) for information on their data handling practices.
   - **LibreTranslate**: Transcribed text is transmitted to the LibreTranslate API for translation. The default instance is hosted at trans.nhcarrigan.com.

4. **Local Storage**: The Application does not persist any user data to browser storage.

### Terms of Service

The Application's usage is governed by the [global terms of service](https://docs.nhcarrigan.com/#/terms).

#### Application-Specific Terms

1. **API Usage**: Users are responsible for their own Deepgram API usage and associated costs. The Application provides cost estimates but does not guarantee accuracy.

2. **Demo API Key**: The translation service demo API key is provided for testing purposes only and has rate limits (10 requests/minute). It may be revoked or changed at any time.

3. **Service Availability**: The Application depends on third-party services (Deepgram and LibreTranslate). Service interruptions may occur due to factors outside of our control.

4. **Accuracy**: The Application provides translation services based on third-party APIs. Translation accuracy is not guaranteed and should not be relied upon for critical communications.

### Security Policy

For security concerns, please refer to the [SECURITY.md](SECURITY.md) file in the repository.

## 4. Contributing Documentation

This section is for documentation related to contributing to the Application's codebase.

### Contributing Guidelines

General contributing guidelines can be found at: https://docs.nhcarrigan.com/#/contributing

### Code of Conduct

Before interacting with our community, please read our [Code of Conduct](CODE_OF_CONDUCT.md).

### Development Setup

1. Fork the repository
2. Clone your fork: `git clone <your-fork-url>`
3. Install dependencies: `npm install`
4. Create a feature branch: `git checkout -b feature/your-feature-name`
5. Make your changes
6. Run linting: `npm run lint`
7. Commit your changes with clear commit messages
8. Push to your fork: `git push origin feature/your-feature-name`
9. Open a Pull Request

### Code Style

- Follow the ESLint configuration (`@nhcarrigan/eslint-config`)
- Use TypeScript with strict type checking
- Follow Angular style guide for component and service structure
- Use meaningful variable and function names
- Add comments for complex logic

### Component Guidelines

- Use standalone components (Angular 19+)
- Implement proper lifecycle hooks
- Use reactive programming patterns with RxJS
- Follow Angular dependency injection best practices
- Keep components focused on a single responsibility

### Service Guidelines

- Use `@Injectable({ providedIn: 'root' })` for singleton services
- Implement proper error handling
- Use TypeScript interfaces for type safety
- Document public methods with JSDoc comments

### Testing Guidelines

- Write unit tests for components and services
- Aim for high code coverage
- Test user interactions and edge cases
- Mock external dependencies (APIs, services)

### Pull Request Process

1. Ensure all tests pass
2. Ensure linting passes with zero warnings
3. Update documentation if needed
4. Provide a clear description of changes
5. Reference any related issues
6. Wait for review from maintainers

### Areas for Contribution

- **UI/UX Improvements**: Enhance the user interface and experience
- **Additional Languages**: Expand language support where possible
- **Performance Optimization**: Improve audio processing efficiency
- **Testing**: Increase test coverage
- **Documentation**: Improve user and technical documentation
- **Accessibility**: Enhance accessibility features
- **Error Handling**: Improve error messages and handling
- **Configuration**: Add more configuration options

### Reporting Issues

If you have feedback or a bug report, please post in the #bug-reports forum channel on our Discord community with:
- Clear description of the issue
- Steps to reproduce (for bugs)
- Expected vs actual behaviour
- Browser and OS information
- Screenshots if applicable

### Contact

We may be contacted through:
- [Chat Server](https://chat.nhcarrigan.com)
- Email: contact@nhcarrigan.com

---

**Version**: 1.1.0
**Author**: Naomi Carrigan
