{"id":30061517,"url":"https://github.com/tigo-cmd/text_to_speech_mini_app","last_synced_at":"2025-08-08T02:23:50.755Z","repository":{"id":307344461,"uuid":"1029181626","full_name":"Tigo-cmd/Text_To_Speech_Mini_App","owner":"Tigo-cmd","description":"A Simple text To Speech Mini App Built With Groq API","archived":false,"fork":false,"pushed_at":"2025-07-30T17:48:48.000Z","size":5405,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-30T20:32:27.720Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://text-to-speech-mini-app.vercel.app","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Tigo-cmd.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"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}},"created_at":"2025-07-30T16:36:25.000Z","updated_at":"2025-07-30T17:48:51.000Z","dependencies_parsed_at":"2025-07-30T20:42:38.075Z","dependency_job_id":null,"html_url":"https://github.com/Tigo-cmd/Text_To_Speech_Mini_App","commit_stats":null,"previous_names":["tigo-cmd/text_to_speech_mini_app"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/Tigo-cmd/Text_To_Speech_Mini_App","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tigo-cmd%2FText_To_Speech_Mini_App","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tigo-cmd%2FText_To_Speech_Mini_App/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tigo-cmd%2FText_To_Speech_Mini_App/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tigo-cmd%2FText_To_Speech_Mini_App/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Tigo-cmd","download_url":"https://codeload.github.com/Tigo-cmd/Text_To_Speech_Mini_App/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tigo-cmd%2FText_To_Speech_Mini_App/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":269352136,"owners_count":24402737,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-08T02:00:09.200Z","response_time":72,"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":[],"created_at":"2025-08-08T02:23:49.115Z","updated_at":"2025-08-08T02:23:50.741Z","avatar_url":"https://github.com/Tigo-cmd.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Text-to-Speech Frontend Application\n\nA modern, responsive React application that converts text to speech using a backend TTS API. Built with TypeScript, Tailwind CSS, and modern web technologies.\n\n## ✨ Features\n\n### Core Functionality\n- **Text Input**: Clean textarea with character counter (5,000 character limit)\n- **Voice Selection**: Dropdown menu with available voices from backend\n- **Audio Playback**: Full-featured HTML5 audio player with:\n  - Play/pause controls\n  - Progress scrubbing\n  - Volume control\n  - Time display\n  - Download functionality\n\n### User Experience\n- **Loading States**: Smooth loading indicators during processing\n- **Error Handling**: Comprehensive error messaging with retry functionality\n- **Responsive Design**: Works seamlessly on mobile, tablet, and desktop\n- **Dark Mode**: Automatic system preference detection with manual toggle\n- **Accessibility**: ARIA labels, keyboard navigation, and focus management\n\n### Technical Features\n- **Polling System**: Automatic retry mechanism for backend processing\n- **Request Timeout**: 30-second timeout with abort controller\n- **Error Recovery**: Graceful fallback for failed API requests\n- **Type Safety**: Full TypeScript implementation\n- **Modular Architecture**: Clean component separation and reusability\n\n## 🚀 Quick Start\n\n### Prerequisites\n- Node.js 18+ \n- npm or yarn\n- A running TTS backend API (see API Configuration below)\n\n### Installation\n\n1. **Clone and install dependencies:**\n```bash\ngit clone \u003cyour-repo-url\u003e\ncd text-to-speech-frontend\nnpm install\n```\n\n2. **Configure environment variables:**\n```bash\ncp .env.example .env\n```\n\nEdit `.env` and set your API endpoint:\n```env\nVITE_API_BASE_URL=http://localhost:3000\n```\n\n3. **Start the development server:**\n```bash\nnpm run dev\n```\n\nThe application will be available at `http://localhost:5173`\n\n## 🔧 API Configuration\n\n### Required Backend Endpoints\n\nYour backend API must provide these endpoints:\n\n#### 1. Convert Text to Speech\n```http\nPOST /api/tts\nContent-Type: application/json\n\n{\n  \"text\": \"Hello world\",\n  \"voice\": \"optional-voice-id\",\n  \"format\": \"mp3\"\n}\n```\n\n**Response:**\n```json\n{\n  \"taskId\": \"unique-task-identifier\"\n}\n```\n\n#### 2. Retrieve Generated Audio\n```http\nGET /api/tts/{taskId}\n```\n\n**Responses:**\n- `202 Accepted` - Still processing (frontend will retry)\n- `200 OK` - Audio ready (returns binary audio data with `audio/mpeg` or `audio/wav` content-type)\n- `404 Not Found` - Task not found\n- `500 Internal Server Error` - Processing failed\n\n#### 3. Get Available Voices (Optional)\n```http\nGET /api/tts/voices\n```\n\n**Response:**\n```json\n[\n  {\n    \"id\": \"voice-1\",\n    \"name\": \"Sarah (Neural)\",\n    \"language\": \"en-US\",\n    \"gender\": \"female\"\n  },\n  {\n    \"id\": \"voice-2\",\n    \"name\": \"John (Neural)\",\n    \"language\": \"en-US\", \n    \"gender\": \"male\"\n  }\n]\n```\n\n### API Configuration Options\n\nSet these environment variables in your `.env` file:\n\n```env\n# Backend API base URL (required)\nVITE_API_BASE_URL=http://localhost:3000\n\n# Optional: Custom timeout settings\nVITE_REQUEST_TIMEOUT=30000\nVITE_MAX_RETRIES=10\nVITE_RETRY_DELAY=2000\n```\n\n## 📁 Project Structure\n\n```\nsrc/\n├── components/          # Reusable UI components\n│   ├── AudioPlayer.tsx  # Full-featured audio player\n│   ├── ErrorMessage.tsx # Error display with retry\n│   ├── LoadingSpinner.tsx # Loading indicators\n│   ├── TextToSpeechForm.tsx # Main form component\n│   ├── ThemeToggle.tsx  # Dark/light mode toggle\n│   └── VoiceSelector.tsx # Voice selection dropdown\n├── services/           # API integration layer\n│   └── api.ts          # TTS API client with error handling\n├── types/              # TypeScript definitions\n│   └── tts.ts          # TTS-related interfaces\n├── App.tsx             # Main application component\n├── index.css           # Global styles and utilities\n└── main.tsx            # Application entry point\n```\n\n## 🛠 Available Scripts\n\n```bash\n# Development\nnpm run dev          # Start development server\nnpm run build        # Build for production\nnpm run preview      # Preview production build locally\n\n# Code Quality\nnpm run lint         # Run ESLint\n```\n\n## 🎨 Customization\n\n### Styling\nThe app uses Tailwind CSS with a clean, modern design system:\n- **Colors**: Blue primary, gray neutrals, semantic colors for states\n- **Typography**: Inter font family with proper hierarchy\n- **Spacing**: 8px grid system\n- **Components**: Consistent border radius, shadows, and transitions\n\n### Theme Support\nAutomatic dark mode detection with manual override:\n- Respects system preference\n- Persistent user choice in localStorage\n- Smooth transitions between themes\n\n### Accessibility Features\n- ARIA labels for screen readers\n- Keyboard navigation support\n- Focus indicators\n- Reduced motion respect\n- High contrast support\n\n## 🔧 Environment Variables\n\n| Variable | Description | Default | Required |\n|----------|-------------|---------|----------|\n| `VITE_API_BASE_URL` | Backend API base URL | `http://localhost:3000` | Yes |\n\n## 🚦 Error Handling\n\nThe application includes comprehensive error handling:\n\n- **Network Errors**: Automatic retry with exponential backoff\n- **Timeout Handling**: 30-second request timeout with user feedback  \n- **Validation**: Client-side input validation with helpful messages\n- **API Errors**: Proper error message display from backend responses\n- **Audio Errors**: Graceful handling of audio playback issues\n\n## 🧪 Testing Your API\n\nYou can test your backend API endpoints using curl:\n\n```bash\n# Test text submission\ncurl -X POST http://localhost:3000/api/tts \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"text\":\"Hello world\",\"format\":\"mp3\"}'\n\n# Test audio retrieval (replace TASK_ID with actual ID)\ncurl -X GET http://localhost:3000/api/tts/TASK_ID \\\n  --output test-audio.mp3\n\n# Test voices endpoint\ncurl -X GET http://localhost:3000/api/tts/voices\n```\n\n## 📝 License\n\nMIT License - feel free to use this project for personal or commercial purposes.\n\n## 🤝 Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests if applicable\n5. Submit a pull request\n\n## 📞 Support\n\nFor questions or issues:\n1. Check the browser console for error messages\n2. Verify your backend API is running and accessible\n3. Confirm environment variables are set correctly\n4. Test API endpoints directly using curl or Postman\n\n## 🔮 Future Enhancements\n\nPotential improvements for future versions:\n- **Batch Processing**: Convert multiple texts simultaneously\n- **Audio History**: Save and manage previous conversions\n- **Custom Voices**: Upload and use custom voice models\n- **SSML Support**: Advanced speech markup language features\n- **WebSocket**: Real-time processing status updates\n- **Audio Editing**: Basic trim, fade, and speed controls","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftigo-cmd%2Ftext_to_speech_mini_app","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftigo-cmd%2Ftext_to_speech_mini_app","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftigo-cmd%2Ftext_to_speech_mini_app/lists"}