BabylPhysh Terminal v0.8a3 - Professional Manual

🎬 BABYLPHYSH TERMINAL

Professional Subtitle Production Management System

v0.8a3-Enterprise

System Overview

Status: Production Ready
Release Date: October 2025
Architecture: Modular Python Package with Real API Integration

BabylPhysh Terminal is a comprehensive subtitle production management system designed for professional documentary film workflows. It provides quality control, multi-language translation with real OpenAI API integration, batch processing, and intelligent file management capabilities.

🆕 What's New in v0.8a3-Enterprise

Real OpenAI Translation Integration

Real API Translation: Actual OpenAI GPT-3.5-turbo translation (not demo mode)
Easy Configuration: Press "C" to paste your API key - automatic detection and testing
Built-in Testing: Press "T" to verify your API connection anytime
Smart Fallback: Automatically falls back to demo mode if API unavailable
Sound Effect Preservation: Maintains [music], [applause], timing markers

User-Friendly API Setup

Auto-detects OpenAI, Google, Azure keys
Tests API before saving
Clear error messages with solutions
No manual CSV editing needed

Enhanced Translation

Professional subtitle-focused prompts
Maintains formatting and timing
Progress indicators during translation
Token usage tracking

Quality Improvements

Frame rate detection
Universal file selection
Enhanced reporting
111+ language support

Terminal Interface

Main Menu Display

╔══════════════════════════════════════════════════════════════════╗ ║ 🎬 BABYLPHYSH TERMINAL v0.8a3-Enterprise ║ ║ Professional Subtitle Production System ║ ╚══════════════════════════════════════════════════════════════════╝ CORE PROCESSING MODES: ---------------------------------------------------------------------- 1) QC-A - Quality Check Analysis (No Changes) 2) QC-FX - Quality Check & Fix 3) QC-DIFF - Compare Original vs Processed 4) TRANS - Translation ← Real OpenAI API! 5) BT-QC - Back-Translation Quality Check 6) CONFORM - Language Conforming 7) SYNC - Transcript Sync 8) SRT-NAME - Batch Append Language Names ENHANCED WORKFLOW MODES: ---------------------------------------------------------------------- 9) BATCH-QC - Batch Quality Control A) ANALYSIS - Enhanced Analysis Dashboard SYSTEM: ---------------------------------------------------------------------- C) CONFIG-API - Configure OpenAI API Key NEW! T) API-TEST - Test Current API Configuration NEW! 0) Exit ====================================================================== Enhanced v0.8a3 Features: • Real OpenAI translation (when API key configured) • Universal file selection: 'all', '1-10', '1,3,5' • Automatic frame rate detection • Professional reporting with metadata • 111+ language support ======================================================================

🔑 API Configuration Guide

Quick Setup (Recommended)

Run BabylPhysh: python3 launch.py
Press: C
Paste your OpenAI API key
BabylPhysh will auto-detect, test, and save it
Done! Your translations now use real OpenAI API
            

Getting Your OpenAI API Key

Go to: platform.openai.com/api-keys
Sign in or create an account
Click "Create new secret key"
Copy the key (starts with "sk-proj-" or "sk-")
Paste it in BabylPhysh when prompted (press C)

Testing Your API

# From BabylPhysh main menu:
Select mode: T

# You'll see:
🔄 Testing OpenAI API connection...
   Model: gpt-3.5-turbo
   Sending test request...

✅ SUCCESS! OpenAI API is working!
   Test translation: 'Hola, ¿cómo estás?'
   Total tokens: 31

🚀 You're ready to use real translation in TRANS mode!
            

API Configuration Options

Provider	Status (v0.8a3)	Auto-Detection
OpenAI	✓ Active	Keys starting with "sk-"
Google Translate	Configuration Ready	Keys starting with "AIza"
Azure Translator	Configuration Ready	32-character hex keys
Demo Mode	Always Available (Fallback)	Automatic when no API

⚠️ Important: OpenAI API usage incurs costs. Check your usage at platform.openai.com/usage. Typical translation costs are approximately $0.002-0.005 per subtitle line with GPT-3.5-turbo.

Core Features - v0.8a3-Enterprise

1. QC-A: Quality Analysis

CPL/CPS/Duration checks
Reading speed analysis
HTML/CSV reports
No file modifications

2. QC-FX: Quality Fix

All QC-A analysis
Automatic corrections
Frame grid alignment
Before/after reports

3. QC-DIFF: Comparison

Visual diff highlighting
Timing analysis
Change tracking
Color-coded output

4. TRANS: Translation ENHANCED!

Real OpenAI API integration
Language packages
Progress tracking
Sound effect preservation

5. BT-QC: Back-Translation

Back-translation analysis
Similarity scoring
Quality assessment
Statistical reporting

6. CONFORM: Language Fix

English remnant detection
Mixed script fixing
Sound effect translation
Consistency checking

7. SYNC: Alignment

Text-to-timing alignment
Fuzzy matching
Auto distribution
Confidence scoring

8. SRT-NAME: Detection

Auto language detection
Filename + content analysis
Batch renaming
111+ language support

9. BATCH-QC: Processing

Multi-file selection
Batch analysis/fix
Progress tracking
Summary reports

A. ANALYSIS: Dashboard

File statistics
Quality scoring
Workflow insights
Comparative analysis

C. CONFIG-API: Setup NEW!

Paste API key
Auto-detect provider
Test before saving
Clear error messages

T. API-TEST: Verify NEW!

Test API connection
Show configuration status
Token usage display
Troubleshooting help

Installation & Setup

Quick Start

# 1. Download from GitHub
https://github.com/growgoo/Babyl/tree/Babylphysh-08a3-Enterprise

# 2. Extract and move to Applications folder

# 3. Open Terminal and navigate
cd /Applications/Babyl-Babylphysh-08a3-Enterprise

# 4. Install dependencies (one-time)
pip3 install -r requirements.txt

# 5. Run BabylPhysh
python3 launch.py
            

System Requirements

Component	Minimum	Recommended
Python Version	3.7	3.9+
RAM	2GB	4GB+
Disk Space	500MB	1GB+
Internet	Required for API	Broadband

Required Dependencies

# These will be installed automatically:
- requests>=2.31.0      (NEW - for API calls)
- chardet>=5.0.0        (file encoding detection)
- python-dateutil>=2.8.0 (timestamp handling)
- PyYAML>=6.0           (configuration files)
- langdetect>=1.0.9     (language detection)
            

Quick User Guide

Basic Workflow

Place English SDH file in masters/ folder
Configure API: Press C and paste your OpenAI key
Test API: Press T to verify connection
Run Mode 4 (TRANS) to generate multiple languages with real translation
Run Mode 6 (CONFORM) to fix partial translations
Run Mode 9 (BATCH-QC) for quality control
Use Mode 8 (SRT-NAME) to organize files
Generate final reports and deliver

Example: Multi-Language Production

# 1. Configure API (one-time setup)
Select mode: C
API Key: sk-proj-YOUR_KEY_HERE
✅ OpenAI API verified and saved!

# 2. Translate to multiple languages
Select mode: 4
Choose file: 1
Select package [1]: 1  (Essential: 5 languages)

# 3. Processing with real OpenAI API
[1/5] Translating to Spanish (Latin America)...
  → Using OpenAI API (gpt-3.5-turbo)...
  ✓ Saved: documentary.es-419.srt

[2/5] Translating to French...
  → Using OpenAI API (gpt-3.5-turbo)...
  ✓ Saved: documentary.fr.srt

[SUCCESS] Translation Complete!
[OUTPUT] 5 language versions in to_qc/
            

Translation Modes Comparison

Feature	Demo Mode	Real API Mode
Translation Quality	Basic word replacement	Professional GPT-3.5-turbo
Context Understanding	None	Full subtitle context
Sound Effects	Simple translation	Preserved as-is
Setup Required	None (always available)	OpenAI API key
Cost	Free	~$0.002-0.005/line
Use Case	Testing, demos	Production delivery

Troubleshooting

API-Related Issues

Problem: Translation uses demo mode instead of real API
Solution: Press C to configure your API key, or press T to test it

Problem: "Invalid API key" error
Solution:

Verify key at platform.openai.com/api-keys
Make sure key starts with "sk-"
Check that key hasn't been revoked
Press C to re-enter your key

Problem: "Rate limit exceeded"
Solution:

Check usage at platform.openai.com/usage
Add credits at billing settings
Wait a few minutes and try again
Demo mode will activate automatically as fallback

General Issues

Problem: "requests library not installed"
Solution: Run: pip3 install requests

Problem: Import errors
Solution: Ensure Python 3.7+ and run: pip3 install -r requirements.txt

Problem: File not found errors
Solution: Verify file paths and folder structure

Problem: Encoding issues
Solution: BabylPhysh auto-detects UTF-8 and Latin-1

Supported Languages

BabylPhysh supports 111+ languages via BCP47 language codes, including:

European Languages

English (US, UK, India, South Africa)
Spanish (Latin America, Spain, US)
French (France, Canada, Senegal)
German (Germany, Austria, Switzerland)
Italian, Dutch, Portuguese
Polish, Czech, Hungarian
Swedish, Norwegian, Danish, Finnish
Romanian, Bulgarian, Greek

Asian Languages

Chinese (Simplified, Traditional)
Japanese, Korean
Hindi, Bengali, Tamil
Thai, Vietnamese, Indonesian
Tagalog, Khmer, Lao
Urdu, Punjabi, Gujarati

Other Languages

Arabic (Standard, Egyptian, Saudi)
Hebrew, Persian, Turkish
Russian, Ukrainian
Swahili, Amharic, Yoruba
Indigenous: Quechua, Aymara, K'iche'

Version History

v0.8a3-Enterprise (October 2025) - CURRENT

Major Features:

Real OpenAI API translation integration
User-friendly API key configuration (press C)
Built-in API testing tool (press T)
Automatic provider detection
Smart fallback to demo mode
Enhanced error messages with solutions

v0.8a2 (September 2025)

Enhancements:

Enhanced SRT-NAME with 111+ language detection
Professional HTML/CSV reporting
Universal source protection
Comprehensive debugging

v0.8a1 (September 2025)

Foundation:

Language database expansion (108+ languages)
Enhanced detection algorithms
BCP47 compliance

v0.8a-enhanced (January 2025)

Initial Release:

27 files, complete subtitle toolkit
8 functional modes, 3 stubs
Demo translation system
ASCII art interface

Contributing & Support

How to Contribute

Report bugs via GitHub Issues
Suggest features in Discussions
Submit pull requests with improvements
Help with documentation
Share your production workflows

Support Resources

Resource	Link
GitHub Repository	github.com/growgoo/Babyl
Issue Tracker	github.com/growgoo/Babyl/issues
Documentation	mysticmayamovie.com/subtitle-toolkit
OpenAI API Keys	platform.openai.com/api-keys
OpenAI Usage	platform.openai.com/usage

Development Setup

# Clone repository
git clone https://github.com/growgoo/Babyl.git
cd Babyl
git checkout Babylphysh-08a3-Enterprise

# Install dependencies
pip3 install -r requirements.txt

# Run tests
python3 launch.py

# Create feature branch
git checkout -b feature/your-feature

# Make changes and test
python3 launch.py

# Commit and push
git commit -m "Add your feature"
git push origin feature/your-feature

# Open Pull Request on GitHub
            

💰 API Cost Estimates

OpenAI GPT-3.5-Turbo Pricing

Based on current OpenAI pricing (as of October 2025):

Usage Type	Cost
Input tokens	$0.50 per 1M tokens
Output tokens	$1.50 per 1M tokens

Estimated Translation Costs

Project Size	Subtitle Count	Estimated Cost per Language
Short Video	100 subtitles	~$0.20 - $0.50
Documentary Episode	500 subtitles	~$1.00 - $2.50
Feature Film	1,500 subtitles	~$3.00 - $7.50
Large Project	5,000 subtitles	~$10.00 - $25.00

Example: Translating a 90-minute documentary (~1,200 subtitles) to 5 languages would cost approximately $15-30 total using GPT-3.5-turbo.

💡 Cost Saving Tips:

Test with demo mode first to verify workflow
Use API mode only for final production translations
Monitor usage at platform.openai.com/usage
Set usage limits in your OpenAI account
Consider batching multiple projects together

📋 Best Practices

Translation Workflow

Prepare Source: Ensure English SDH file is clean and properly formatted
Test API: Press T to verify connection before large jobs
Start Small: Test with 1-2 languages first
Review Output: Check one translated file before processing all languages
Use QC Modes: Run BATCH-QC to verify quality across all translations
Save Originals: BabylPhysh protects masters/ folder automatically
Document Changes: Use RUN_LOG.txt to track operations

API Key Security

🔒 Security Best Practices:

Never share your API key publicly
Don't commit api_config.csv to public repositories
Rotate keys periodically
Set usage limits in OpenAI dashboard
Monitor usage regularly for unexpected activity
Revoke and replace if key is compromised

Quality Control Tips

CPL (Characters Per Line): Keep under 42 for FilmHub compliance
CPS (Characters Per Second): Target 17 or lower for readability
Duration: Maintain 1000-7000ms for proper timing
Sound Effects: Verify [music], [applause] preserved in translations
Formatting: Check line breaks maintained correctly
Cultural Context: Review idioms and cultural references

🔧 Technical Specifications

Supported File Formats

Format	Input	Output
SRT (SubRip)	✓	✓
HTML Reports	—	✓
CSV Data	—	✓
Text Logs	—	✓

Encoding Support

UTF-8: Primary encoding (recommended)
Latin-1: Auto-detected fallback
Detection: Automatic with chardet library
Output: Always UTF-8 for maximum compatibility

Frame Rate Support

Frame Rate	Common Use	Support
23.976 fps	Film, Cinema	✓ Auto-detected
24 fps	Film	✓ Auto-detected
25 fps	PAL, Europe	✓ Auto-detected
29.97 fps	NTSC, US TV	✓ Auto-detected
30 fps	US TV	✓ Auto-detected
50 fps	High frame rate	✓ Auto-detected
59.94/60 fps	High frame rate	✓ Auto-detected

Performance Characteristics

Metric	Specification
File Processing	Up to 10,000+ subtitles per file
Batch Operations	20+ files simultaneously
Memory Usage	~50MB typical, ~200MB heavy processing
Translation Speed	~1-2 seconds per subtitle (API dependent)
QC Processing	~1000 subtitles per second

⌨️ Keyboard Shortcuts & Tips

Terminal Navigation

Ctrl+C          - Cancel current operation
Ctrl+D          - Exit application
Arrow Up/Down   - Recall previous commands
Tab             - Auto-complete file paths (in Terminal)
Cmd+K           - Clear Terminal screen (Mac)
            

Quick Selection Patterns

Pattern	Description	Example
all	Select all available files	Process entire batch
1-10	Range selection	Files 1 through 10
1,3,5	Multiple specific files	Files 1, 3, and 5 only
1	Single file	Just file #1

📖 Glossary

Term	Definition
API	Application Programming Interface - allows BabylPhysh to communicate with OpenAI's translation service
BCP47	Language code standard (e.g., en-US, es-419, fr-CA)
CPL	Characters Per Line - maximum characters allowed on one subtitle line
CPS	Characters Per Second - reading speed metric for subtitle display time
GPT-3.5-turbo	OpenAI's fast, efficient language model used for translation
SDH	Subtitles for the Deaf and Hard of hearing - includes sound effects and speaker identification
SRT	SubRip Text - standard subtitle file format
Token	Unit of text processing for API billing (~4 characters = 1 token)
Frame Rate	Frames per second (fps) - timing precision for video/subtitle synchronization