✨ 1. Pengenalan & Fitur Utama

SubtitledByAI adalah sistem otomatis end-to-end yang dirancang khusus untuk para fansub/subber variety show idol Jepang. Proyek ini memecahkan tantangan umum dalam subtitling otomatis (seperti tumpang tindih suara saat member tertawa/berbicara bersamaan, istilah khusus idol, dan ketepatan timing per dialog).

Dukungan Grup & Show Idol

🚀 2. Instalasi & Menjalankan

Langkah pertama adalah melakukan clone repository resmi SubtitledByAI dari GitHub ke komputer lokal Anda:

git clone https://github.com/yahyasetz11/SubtitledByAI.git
cd SubtitledByAI

Cara Mendapatkan & Memasang GEMINI_API_KEY

Aplikasi ini membutuhkan API Key dari Google AI Studio (tersedia gratis dengan kuota harian):

1. Buka Google AI Studio (aistudio.google.com) dan login dengan akun Google Anda.
2. Klik tombol "Create API key" / "Get API key".
3. Salin token API key yang dibuat (format: AIzaSy...).
4. Buat/salin file .env dari template di folder proyek:
   PowerShell / Bash Salin

   cp .env.example .env

5. Buka file .env menggunakan teks editor (Notepad / VS Code) dan tempelkan API key Anda:
   .env Salin

   GEMINI_API_KEY=AIzaSyBxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Opsi A — Menjalankan via Docker (Direkomendasikan)

Dengan Docker, dependensi audio seperti ffmpeg dan pustaka sistem lainnya sudah terpasang otomatis di dalam container tanpa perlu instalasi manual.

# 1. Pastikan file .env sudah berisi GEMINI_API_KEY
# 2. Build container image
docker compose build

# 3. Jalankan aplikasi
docker compose up

Buka browser di alamat http://localhost:8000. Untuk menghentikan service, tekan Ctrl + C atau jalankan docker compose down.

Opsi B — Menjalankan Lokal (Python 3.11+)

Pastikan sistem Anda telah terpasang Python 3.11+ dan FFmpeg yang terdaftar di PATH lingkungan sistem.

# Install FFmpeg (Windows via Winget)
winget install Gyan.FFmpeg

# Buat virtual environment dan pasang pustaka
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt

# Jalankan server FastAPI
python -m uvicorn app.main:app --port 8000 --reload

⚙️ 3. Konfigurasi Environment (.env)

File .env digunakan untuk mengelola API keys LLM dan hyperparameter pemrosesan subtitle.

💻 4. Panduan Penggunaan Web UI

Antarmuka web SubtitledByAI dirancang intuitif untuk pemrosesan cepat maupun kustomisasi episode khusus.

1. Pilih Grup & Show: Pilih grup idol (misal: Sakurazaka46) dan show (misal: Soko Magattara Sakurazaka?). Sistem otomatis memuat roster member dan glossary terkait.
2. Input Sumber Media: Masukkan URL video YouTube secara langsung atau unggah file lokal Anda (.mp4, .mkv, .mp3, .m4a, .wav).
3. Pilih Model Translasi & Format: Tentukan LLM yang ingin digunakan untuk menerjemahkan (Gemini 3.6 Flash, GPT-4o, atau Claude) serta format output (.ass atau .srt).
4. Konteks Tambahan (Opsional): Masukkan nama bintang tamu spesial atau topik bahasan episode di kolom Additional Context jika diperlukan.
5. Mulai Proses: Klik tombol Mulai Buat Subtitle. Progress pengerjaan setiap stage akan ditampilkan secara live melalui Server-Sent Events (SSE).
6. Unduh & Preview: Setelah selesai, Anda dapat langsung melihat pratinjau video dengan subtitle yang dirender langsung via WebAssembly SubtitlesOctopus dan mengunduh file subtitle.

🔄 5. Alur Pipeline & Arsitektur

Pipeline eksekusi bekerja secara sekuensial dengan sistem checkpointing granular. Jika terjadi gangguan jaringan atau kegagalan API di tengah jalan, Anda cukup menekan tombol Coba Lagi dan proses akan melanjutkan dari titik terakhir tanpa mengulang transkripsi yang sudah selesai.

Fitur Ketahanan Engine:

• 3-Tier Translation Fallback: Penerjemahan dilakukan secara batch (100 baris). Jika LLM merespons format yang salah, sistem otomatis mengulang dengan prompt feedback error, dan jika masih gagal, melakukan fallback per-baris secara mandiri.
• Silence-Based Re-anchoring: Mengoreksi timestamp awal dan akhir dialog dengan mendeteksi segmen hening audio asli menggunakan FFmpeg silencedetect.
• Post-processing 5 Langkah: Penggabungan baris terlalu pendek (<0.7 detik), pemanjangan durasi minimum, pemotongan kalimat terlalu panjang (>7.5 detik), perbaikan tabrakan overlap timestamp, dan pengecekan CPS.

📖 6. Kustomisasi Konteks & Glosarium

Keunggulan utama SubtitledByAI adalah pemahaman konteks idol Jepang. Semua file konteks berada di direktori context/ dan mendukung Hot-Reloading (dibaca ulang pada setiap job tanpa perlu restart server).

📁 7. Struktur & Format Output

Setiap job yang diproses akan menghasilkan folder terisolasi di dalam direktori output/{job_id}/ dengan artefak lengkap:

output/20260818_143022_abc123/
├── result.ass          # Subtitle final format Advanced SubStation Alpha (siap tonton)
├── result.srt          # Subtitle final format SubRip Subtitle standar
├── transcript_jp.json  # Transkrip mentah bahasa Jepang beserta timestamp presisi
├── translated_id.json  # Hasil transkripsi + terjemahan Bahasa Indonesia lengkap
├── flags.json          # Daftar baris dengan CPS > 25 (indikasi teks terlalu panjang)
├── usage.json          # Laporan total token LLM & estimasi biaya (USD)
└── source.mp4          # File video sumber (jika opsi simpan video diaktifkan)

❓ 8. Troubleshooting & FAQ

Q: Download YouTube gagal dengan error "Sign in to confirm you're not a bot"?

Ekspor cookies YouTube akun Anda menggunakan ekstensi browser (format Netscape cookie.txt) lalu letakkan di root proyek sebagai cookie.txt atau atur variabel YTDLP_COOKIES_FILE di .env.

Q: yt-dlp error mengekstrak video terbaru?

YouTube sering memperbarui algoritma pemutar videonya. Perbarui pustaka yt-dlp ke versi paling baru:

# Jika menjalankan lokal:
pip install -U yt-dlp

# Jika menggunakan Docker:
docker compose build --no-cache

Q: Berapa rata-rata biaya API per episode variety show (~25 menit)?

Dengan konfigurasi default (Transkripsi Gemini 3.6 Flash + Translasi Gemini 3.6 Flash + QC), biaya rata-rata sangat hemat dan terjangkau, berkisar antara $0.05 hingga $0.15 USD per episode.

Q: Mengapa ada baris di flags.json?

flags.json mencatat baris dialog yang memiliki nilai CPS (Characters Per Second) di atas 25. Ini menandakan teks terjemahan mungkin terlalu panjang untuk dibaca dalam durasi dialog aslinya, sehingga subber dapat melakukan penyesuaian/pemadatan kata secara manual jika diinginkan.