react-edge-tts/README.md

Generate text-to-speech narration for React content using Microsoft Edge TTS

# React Edge Text-to-Speech

Generate text-to-speech narration for React content using Microsoft Edge's TTS engine. This package allows you to easily add high-quality narration to your React content, such as blog posts, articles, or any text content.

## Features

- 🎯 Simple React component for marking narration content
- 🔊 High-quality text-to-speech using Microsoft Edge's TTS engine
- 🎛️ Multiple voice options (US, UK, Australian accents)
- 🛠️ Build-time content extraction
- 📦 Separate audio generation step for optimal performance

## Installation

```bash
npm install react-edge-tts
# or
yarn add react-edge-tts
```

## Usage

### 1. Add Narration Components

Use the `Narrate` component to wrap content you want to narrate:

```jsx
import { Narrate, VOICE_OPTIONS } from 'react-edge-tts';

function BlogPost() {
  return (
    <article>
      <Narrate
        title='welcome-section'
        voice={VOICE_OPTIONS.US_FEMALE}
        rate={1.1}
      >
        Welcome to my blog post! This text will be converted to speech.
      </Narrate>

      <Narrate title='main-content' voice={VOICE_OPTIONS.GB_MALE}>
        This is the main content of my blog post. It will be narrated with a
        British male voice.
      </Narrate>
    </article>
  );
}
```

### 2. Configure Babel

Add the babel plugin to your babel configuration:

```javascript
// babel.config.js
module.exports = {
  plugins: [
    [
      'react-edge-tts/babel',
      {
        outputDir: 'narration-content', // optional, defaults to 'narration-content'
      },
    ],
  ],
};
```

### 3. Generate Audio

After building your project, run the CLI command to generate audio files:

```bash
npx react-edge-tts generate
```

Or with custom directories:

```bash
npx react-edge-tts generate --input ./my-content --output ./my-audio
```

### 4. Use the Generated Audio

The generated MP3 files will be in your output directory, named according to the `title` prop you provided to each `Narrate` component.

## Component Props

| Prop             | Type          | Default    | Description                                 |
| ---------------- | ------------- | ---------- | ------------------------------------------- |
| `title`          | string        | (required) | Unique identifier for the narration section |
| `voice`          | VoiceId       | US_FEMALE  | Voice to use for narration                  |
| `rate`           | number        | 1          | Speech rate (0.5 to 2)                      |
| `volume`         | number        | 1          | Volume level (0 to 1)                       |
| `pitch`          | number        | 1          | Voice pitch (0.5 to 2)                      |
| `showIndicator`  | boolean       | dev only   | Show narration indicator                    |
| `indicatorStyle` | CSSProperties | undefined  | Custom styles for indicator                 |

## Available Voices

```typescript
VOICE_OPTIONS.US_FEMALE; // en-US-JennyNeural
VOICE_OPTIONS.US_MALE; // en-US-GuyNeural
VOICE_OPTIONS.US_FEMALE_ALT; // en-US-AriaNeural
VOICE_OPTIONS.GB_FEMALE; // en-GB-SoniaNeural
VOICE_OPTIONS.GB_MALE; // en-GB-RyanNeural
VOICE_OPTIONS.AU_FEMALE; // en-AU-NatashaNeural
VOICE_OPTIONS.AU_MALE; // en-AU-WilliamNeural
```

List all available voices:

```bash
npx react-edge-tts list-voices
```

## CLI Commands

| Command       | Description                                 |
| ------------- | ------------------------------------------- |
| `generate`    | Generate audio files from narration content |
| `list-voices` | List all available voices                   |

### Generate Command Options

| Option         | Default           | Description                           |
| -------------- | ----------------- | ------------------------------------- |
| `--input, -i`  | narration-content | Input directory containing JSON files |
| `--output, -o` | narration-audio   | Output directory for MP3 files        |

## Development Indicators

In development mode, narrated sections will show a small indicator. Control this with the `showIndicator` prop:

```jsx
<Narrate
  title='section'
  showIndicator={true} // Force show in production
  indicatorStyle={{ color: 'blue' }} // Custom styling
>
  Content
</Narrate>
```

## License

GPL-3.0

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.