gTts_n8n_telegram_bot

# 🎙️ Telegram Voice Bot - TTS API

Telegram için yapay zeka destekli sesli mesaj üretim sistemi. Google Text-to-Speech (gTTS) ve N8N workflow'u kullanarak metin mesajlarını yüksek kaliteli sesli mesajlara dönüştürür.

## ✨ Özellikler

- 🇹🇷 **Doğal Türkçe TTS**: Google TTS ile profesyonel ses kalitesi
- 🎵 **Çoklu Format Desteği**: MP3 ve OGG formatları (Telegram optimize)
- ⚡ **Hızlı İşlem**: 3-5 saniye içinde sesli mesaj üretimi
- 🤖 **N8N Entegrasyonu**: Otomatik workflow yönetimi
- 📱 **Telegram Optimize**: Telegram'a özel ses formatı
- 🔄 **Auto-Cleanup**: Geçici dosyaların otomatik temizlenmesi
- 🌐 **CPanel Uyumlu**: Shared hosting desteği
- 📊 **Health Check**: API sağlık durumu izleme

## 🚀 Kurulum

### Gereksinimler

- Python 3.10+
- Flask
- gTTS (Google Text-to-Speech)
- Docker (N8N için)
- ngrok (webhook tunnel için)

### 1. Repoyu Klonlayın

```bash
git clone https://github.com/yourusername/gTts-telegram.git
cd gTts-telegram
```

### 2. Sanal Ortam Oluşturun

```bash
python -m venv .venv
source .venv/bin/activate  # Linux/Mac
# veya
.venv\Scripts\activate     # Windows
```

### 3. Bağımlılıkları Yükleyin

```bash
pip install -r requirements.txt
```

### 4. Dizinleri Oluşturun

```bash
mkdir -p voice_messages temp_voice shared
```

## 🔧 Yapılandırma

### Environment Değişkenleri

Projenizde `.env` dosyası oluşturun:

```env
# Flask Ayarları
FLASK_ENV=production
FLASK_DEBUG=False

# TTS Ayarları
TTS_DEFAULT_LANG=tr
TTS_DEFAULT_FORMAT=ogg
TTS_MAX_TEXT_LENGTH=1000
TTS_CLEANUP_HOURS=1

# Telegram Bot (N8N'de yapılandırılacak)
# TELEGRAM_BOT_TOKEN=your_bot_token_here

# API Ayarları
API_HOST=0.0.0.0
API_PORT=5001
```

### Telegram Bot Kurulumu

1. [@BotFather](https://t.me/botfather) ile yeni bot oluşturun
2. Bot token'ını alın
3. N8N'de Telegram credentials'ını yapılandırın

## 🏃‍♂️ Çalıştırma

### Geliştirme Ortamı

```bash
# Flask API'sini çalıştır
python app.py

# API testini çalıştır
python test_api.py
```

### Production Ortamı (Docker + N8N)

```bash
# ngrok ve N8N'i başlat
chmod +x start-ngrok.sh
./start-ngrok.sh

# Durum kontrolü
chmod +x status.sh
./status.sh
```

### Manuel Docker Kurulumu

```bash
# N8N'i başlat
docker-compose -f docker-compose.webhook.yml up -d

# Logları kontrol et
docker-compose -f docker-compose.webhook.yml logs -f
```

## 📡 API Endpoints

### Temel Endpoints

| Method | Endpoint | Açıklama |
|--------|----------|----------|
| GET | `/` | API bilgileri |
| GET | `/health` | Sağlık kontrolü |
| POST | `/generate_tts` | TTS üretimi |
| GET | `/download/<filename>` | Ses dosyası indirme |

### TTS API Kullanımı

```bash
# POST /generate_tts
curl -X POST http://localhost:5001/generate_tts \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Merhaba! Bu bir test mesajıdır.",
    "lang": "tr",
    "format": "ogg",
    "user_name": "Test User"
  }'
```

### Response Formatı

```json
{
  "success": true,
  "message": "Sesli mesaj başarıyla oluşturuldu (OGG)",
  "audio_file": "/path/to/voice_file.ogg",
  "download_url": "/download/voice_12345.ogg",
  "file_info": {
    "filename": "voice_12345.ogg",
    "format": "ogg",
    "size_bytes": 15420,
    "duration_seconds": 3.2
  },
  "user_name": "Test User",
  "timestamp": "2024-01-01T12:00:00Z"
}
```

## 🔌 N8N Workflow

N8N workflow'u otomatik olarak:

1. Telegram mesajlarını dinler
2. Metin mesajlarını TTS API'sine gönderir
3. Oluşturulan ses dosyasını kullanıcıya gönderir
4. Hata durumlarını yönetir
5. API sağlığını izler

### Workflow İçe Aktarma

```bash
# N8N arayüzünde
# Settings > Import from file > telegram-voice-bot-final.json
```

## 🧪 Test

### API Testleri

```bash
# Tüm testleri çalıştır
python test_api.py

# Manuel test endpoints
curl http://localhost:5001/test      # MP3 test
curl http://localhost:5001/test_ogg  # OGG test
```

### Test Sonuçları

```
🎯 TEST SONUÇLARI
================
API Health      | ✅ BAŞARILI
MP3 TTS        | ✅ BAŞARILI  
OGG TTS        | ✅ BAŞARILI
Custom TTS     | ✅ BAŞARILI
File Download  | ✅ BAŞARILI
List Voices    | ✅ BAŞARILI

📊 Özet: 6 başarılı, 0 başarısız
```

## 📁 Proje Yapısı

```
gTts-telegram/
├── app.py                          # Ana Flask uygulaması
├── test_api.py                     # API test scriptleri
├── requirements.txt                # Python bağımlılıkları
├── docker-compose.webhook.yml      # N8N Docker yapılandırması
├── telegram-voice-bot-final.json   # N8N workflow
├── start-ngrok.sh                  # ngrok başlatma scripti
├── status.sh                       # Sistem durum kontrolü
├── restart-bot.sh                  # Sistem yeniden başlatma
├── voice_messages/                 # Üretilen ses dosyaları
├── temp_voice/                     # Geçici dosyalar
├── shared/                         # N8N paylaşılan dosyalar
└── .venv/                          # Python sanal ortamı
```

## 🔧 Sorun Giderme

### Yaygın Sorunlar

**1. TTS API Erişim Hatası**
```bash
# Flask uygulamasının çalıştığını kontrol edin
curl http://localhost:5001/health
```

**2. N8N Webhook Sorunu**
```bash
# N8N container'ının çalıştığını kontrol edin
docker ps --filter "name=n8n-webhook"
```

**3. ngrok Bağlantı Sorunu**
```bash
# ngrok durumunu kontrol edin
./status.sh
```

**4. Ses Dosyası Üretim Hatası**
```bash
# Disk alanını kontrol edin
df -h

# Dizin izinlerini kontrol edin
ls -la voice_messages/ temp_voice/
```

### Debug Modunda Çalıştırma

```bash
export FLASK_DEBUG=True
python app.py
```

### Logları İnceleme

```bash
# N8N logları
docker-compose -f docker-compose.webhook.yml logs -f

# ngrok logları
tail -f ngrok.log

# Sistem logları
tail -f /var/log/system.log
```

## 🔒 Güvenlik

### API Token Güvenliği

- Telegram bot token'ı N8N credentials'ında saklanır
- API endpoint'leri rate limiting ile korunur
- Geçici dosyalar otomatik olarak temizlenir
- Güvenli file upload/download yönetimi

### Üretim Ortamı İçin

```bash
# HTTPS kullanın
# Firewall kuralları oluşturun  
# Regular güvenlik güncellemeleri yapın
# Backup stratejisi oluşturun
```

## 📈 Performans

### Optimizasyon Önerileri

- **Disk Temizleme**: Otomatik 1 saatlik temizlik aktif
- **Memory Management**: Process bazlı memory sınırları
- **Concurrent Requests**: N8N concurrency: 10
- **File Size Limits**: TTS max 1000 karakter

### Monitoring

```bash
# API response time
curl -w "@curl-format.txt" http://localhost:5001/health

# Memory usage
ps aux | grep python

# Disk usage
du -sh voice_messages/ temp_voice/
```

## 🤝 Katkı Sağlama

1. Fork yapın
2. Feature branch oluşturun (`git checkout -b feature/amazing-feature`)
3. Değişikliklerinizi commit edin (`git commit -m 'Add amazing feature'`)
4. Branch'inizi push edin (`git push origin feature/amazing-feature`)
5. Pull Request oluşturun

## 📝 Changelog

### [1.0.0] - 2024-01-01
- İlk sürüm
- Telegram entegrasyonu
- MP3/OGG format desteği
- N8N workflow
- CPanel hosting desteği

## 📄 Lisans

Bu proje MIT Lisansı altında lisanslanmıştır. Detaylar için [LICENSE](LICENSE) dosyasına bakın.

## 👥 İletişim

- **Geliştirici**: Can Uzlaş
- **Email**: canuzlass@gmail.com
- **GitHub**: [@yourusername](https://github.com/canuzlas)

## 🙏 Teşekkürler

- [Google Text-to-Speech](https://cloud.google.com/text-to-speech) - TTS servisi
- [N8N](https://n8n.io/) - Workflow otomasyonu
- [Flask](https://flask.palletsprojects.com/) - Web framework
- [Telegram Bot API](https://core.telegram.org/bots/api) - Bot entegrasyonu

---

⭐ Bu projeyi beğendiyseniz yıldız vermeyi unutmayın!

🐛 Bug raporu veya özellik isteği için [Issues](https://github.com/canuzlas/gTts_n8n_telegram_bot/issues) bölümünü kullanın.

📚 Daha fazla dokümantasyon için [Wiki](https://github.com/canuzlas/gTts_n8n_telegram_bot/wiki) sayfasını ziyaret edin.