{"id":50758870,"url":"https://github.com/knguyen1411b/text-to-speech-api","last_synced_at":"2026-06-11T08:01:19.414Z","repository":{"id":360036545,"uuid":"1248438847","full_name":"knguyen1411b/text-to-speech-api","owner":"knguyen1411b","description":"A lightweight, secure, and production-ready Express \u0026 TypeScript API designed to convert text into high-quality speech audio files using the Google Translate TTS engine. It splits long texts semantically into parallel chunks and streams them back combined as a single audio file.","archived":false,"fork":false,"pushed_at":"2026-05-24T17:04:07.000Z","size":490,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-24T19:06:53.223Z","etag":null,"topics":["tts-api"],"latest_commit_sha":null,"homepage":"https://text-to-speech-api-v1.vercel.app","language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/knguyen1411b.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-24T16:37:23.000Z","updated_at":"2026-05-24T17:04:10.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/knguyen1411b/text-to-speech-api","commit_stats":null,"previous_names":["knguyen1411b/text-to-speech-api"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/knguyen1411b/text-to-speech-api","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/knguyen1411b%2Ftext-to-speech-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/knguyen1411b%2Ftext-to-speech-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/knguyen1411b%2Ftext-to-speech-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/knguyen1411b%2Ftext-to-speech-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/knguyen1411b","download_url":"https://codeload.github.com/knguyen1411b/text-to-speech-api/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/knguyen1411b%2Ftext-to-speech-api/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34188272,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-11T02:00:06.485Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["tts-api"],"created_at":"2026-06-11T08:01:18.868Z","updated_at":"2026-06-11T08:01:19.408Z","avatar_url":"https://github.com/knguyen1411b.png","language":"HTML","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Text-to-Speech (TTS) API\n\nA lightweight, secure, and production-ready Express \u0026 TypeScript API designed to convert text into high-quality speech audio files using the Microsoft Edge Neural TTS engine. It splits long texts semantically into parallel chunks and streams them back combined as a single audio file.\n\n![API Playground Screenshot](./public/image.png)\n\n---\n\n## 🚀 Features\n\n- **Text-to-Speech Conversion:** Converts any string of text into a downloadable `.mp3` audio stream.\n- **Smart Text Chunking:** Semantically splits long paragraphs into chunks of under 2000 characters to optimize phrasing context and comply with Edge TTS limits, preserving natural sentence/word transitions.\n- **Parallel Chunk Fetching:** Processes and downloads text chunks in parallel for ultra-fast response times.\n- **API Key Security:** Protects routes using flexible authorization headers, bearer tokens, or query keys.\n- **TypeScript First:** Reorganized, fully typed, and structured codebase.\n- **Production-ready Testing:** Integrated with Jest, ts-jest, and Supertest for unit and integration testing.\n- **Vercel Serverless Ready:** Deploy directly to Vercel without manual compilation.\n\n---\n\n## 📂 Project Architecture\n\n```\n├── .github/\n│   └── workflows/\n│       └── ci.yml             # GitHub Actions CI pipeline\n├── src/\n│   ├── middlewares/\n│   │   └── auth.ts            # API Key authentication middleware\n│   ├── controllers/\n│   │   └── ttsController.ts   # TTS generation \u0026 stream merging logic\n│   ├── routes/\n│   │   └── ttsRoutes.ts       # Route endpoints mapping\n│   ├── utils/\n│   │   └── textSplitter.ts    # Semantic text splitting utility\n│   ├── app.ts                 # Express application instantiation\n│   └── server.ts              # Local listener server entry point\n├── tests/\n│   ├── auth.test.ts           # Authentication tests\n│   ├── textSplitter.test.ts   # Splitting logic unit tests\n│   └── tts.test.ts            # Endpoint integration tests\n├── .env.example               # Configuration example\n├── tsconfig.json              # TypeScript compilation parameters\n├── vercel.json                # Vercel Serverless routing config\n└── README.md                  # Project documentation\n```\n\n---\n\n## 🛠️ Getting Started\n\n### Prerequisites\n\n- Node.js (version 18 or 20 recommended)\n- `pnpm` (or `npm`/`yarn` equivalent)\n\n### Installation \u0026 Setup\n\n1. **Clone the Repository:**\n   ```bash\n   git clone https://github.com/your-username/text-to-speech-api.git\n   cd text-to-speech-api\n   ```\n\n2. **Install Dependencies:**\n   ```bash\n   pnpm install\n   ```\n\n3. **Configure Environment:**\n   Create a `.env` file using the template:\n   ```bash\n   cp .env.example .env\n   ```\n   Modify `.env` and set your secret API Key:\n   ```env\n   API_KEY=your_secret_api_key_here\n   PORT=3000\n   ```\n\n4. **Run the Development Server:**\n   ```bash\n   pnpm dev\n   ```\n   The local server will start at `http://localhost:3000`.\n\n---\n\n## 📖 API Reference\n\nAll requests must be authenticated. The API key can be supplied in one of three ways:\n1. Custom header: `x-api-key: your_secret_api_key_here`\n2. Authorization header: `Authorization: Bearer your_secret_api_key_here`\n3. Query Parameter: `?key=your_secret_api_key_here`\n\n---\n\n### Get Speech (GET Request)\n\nIdeal for embedding directly in `\u003caudio\u003e` HTML elements.\n\n- **URL:** `/api/tts`\n- **Method:** `GET`\n- **Query Parameters:**\n  - `key` (Required): Your API Key.\n  - `text` (Required): The text content you want to convert.\n  - `lang` (Optional): Target language code (default: `vi` for Vietnamese. Supports `en`, `ja`, `ko`, `fr`, etc.).\n\n**Example HTML Integration:**\n```html\n\u003caudio controls\u003e\n  \u003csource src=\"http://localhost:3000/api/tts?key=your_secret_api_key_here\u0026text=Hello+World\u0026lang=en\" type=\"audio/mpeg\"\u003e\n\u003c/audio\u003e\n```\n\n---\n\n### Get Speech (POST Request)\n\nIdeal for API calls from backends or frontend applications sending large blocks of text.\n\n- **URL:** `/api/tts`\n- **Method:** `POST`\n- **Headers:**\n  - `Content-Type: application/json`\n  - `x-api-key: your_secret_api_key_here`\n- **Request Body (JSON):**\n  ```json\n  {\n    \"text\": \"This is a longer text that will be converted into speech audio.\",\n    \"lang\": \"en\"\n  }\n  ```\n\n- **Success Response:**\n  - **Status:** `200 OK`\n  - **Content-Type:** `audio/mpeg`\n  - **Headers:** `Content-Disposition: attachment; filename=\"speech.mp3\"`\n  - **Body:** Binary audio stream (MP3 format).\n\n---\n\n## 🧪 Testing\n\nThe repository includes a comprehensive unit and integration test suite configured with Jest.\n\n- **Run all tests:**\n  ```bash\n  pnpm test\n  ```\n\n- **Run tests in watch mode:**\n  ```bash\n  pnpm test -- --watch\n  ```\n\n- **Run tests with coverage:**\n  ```bash\n  pnpm test:cov\n  ```\n\n---\n\n## 🚀 Deployment\n\n### Deploy to Vercel\n\nThe project is pre-configured to deploy seamlessly to Vercel as a Serverless function.\n\n1. Install the Vercel CLI (`npm install -g vercel`) or connect the repo to the Vercel Dashboard.\n2. Run the deployment:\n   ```bash\n   vercel\n   ```\n3. Add the `API_KEY` Environment Variable in your Vercel Dashboard project settings.\n\n### Docker / Production Server\n\nTo compile the TypeScript code and run the node bundle manually:\n\n```bash\npnpm build\npnpm start\n```\nThe compiled code will be output to `/dist/` and runs the production node server.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fknguyen1411b%2Ftext-to-speech-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fknguyen1411b%2Ftext-to-speech-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fknguyen1411b%2Ftext-to-speech-api/lists"}