webnative-services

A Text-to-Speech REST API service using local Piper models via sherpa-onnx. Provides high-quality voice synthesis with multiple English voices.

Installation

Global Installation

npm install -g webnative-services
webnative-services

Using npx (No Installation Required)

npx webnative-services

The server will start and display the available endpoints:

Starting webnative-services...
Text-to-Speech REST API
========================

Server is running on:
  ➜  http://localhost:3000
  ➜  http://192.168.1.x:3000

Development Setup

1. Clone the repository
2. Install dependencies:

   bun install

3. Run the development server:

   bun run dev

API Endpoints

GET /help

Returns API documentation in JSON format.

GET /voices

Returns a list of available voice models.

Response:

{
  "voices": [
    "en_US-amy-medium",
    "en_GB-alan-medium",
    ...
  ]
}

POST /tts

Generates speech from text.

Query Parameters:

• voice (optional): The name of the voice model to use (e.g., en_US-amy-medium). Defaults to en_US-amy-medium.

Body:

{
  "text": "The text to convert to speech"
}

Response: Returns an audio file (audio/wav).

Example:

curl -X POST "http://localhost:3000/tts?voice=en_US-amy-medium" \
     -H "Content-Type: application/json" \
     -d '{"text": "Hello world"}' \
     --output output.wav

Available Voices

(Check GET /voices for the most up-to-date list)

• en_GB-alan-medium
• en_GB-alba-medium
• en_GB-aru-medium
• en_GB-cori-high
• en_GB-cori-medium
• en_GB-jenny_dioco-medium
• en_GB-northern_english_male-medium
• en_GB-semaine-medium
• en_GB-vctk-medium
• en_US-amy-medium
• en_US-bryce-medium
• en_US-hfc_female-medium
• en_US-hfc_male-medium
• en_US-joe-medium
• en_US-kusal-medium
• en_US-lessac-high
• en_US-lessac-medium
• en_US-libritts-high
• en_US-ryan-high
• en_US-ryan-medium

Publishing to NPM

Automated Publishing (Recommended)

This repository includes a GitHub Action workflow that automatically publishes to npm when a new release is created.

1. Configure Secrets:

   • Go to repository Settings → Secrets and variables → Actions
   • Add a repository secret named NPM_TOKEN with your npm automation token.

2. Trigger Release:

   • Update the version in package.json:

     npm version patch  # or minor, or major

   • Push changes and tags:

     git push origin main --tags

   • Create a release on GitHub using the new tag (e.g., v0.1.1).
   • The "Publish Package" workflow will run automatically, building, testing, and publishing the package.

Manual Publishing

For maintainers who want to publish updates manually:

1. Login to npm (first time only):

   npm login

2. Test the package locally:

   npm link
   npx webnative-services

3. Verify package contents:

   npm pack --dry-run

4. Publish to npm:

   npm publish
   # Note: prepublishOnly script will automatically run 'npm run build'

License

MIT