AI Voice Studio

Installation & Customization Documentation

Overview

AI Voice Studio is a comprehensive PHP-based web application for generating AI-powered text-to-speech audio, custom ringtones, and song lyrics. It features 30+ unique voice personas, user authentication system with premium subscriptions, audio file management, admin dashboard, payment integration with Stripe, and a modern responsive UI. This guide explains how to install, configure, and customize the script for your needs.

Key Features

  • User Authentication: Registration, login, profile management
  • Premium Subscriptions: Free and premium tiers with different voice access
  • Payment Processing: Stripe integration with subscription management
  • Audio Management: Save, organize, and manage generated audio files
  • Admin Dashboard: Complete admin panel for user and system management
  • Generation Limits: Configurable daily limits for free and premium users
  • Storage Management: Track and manage user storage usage
  • Failed Payment Recovery: Comprehensive system for handling payment failures with automatic retry logic
  • Analytics Integration: Google Analytics support

1. Installation

  1. Requirements:
    • PHP 7.4 or higher with MySQL support
    • MySQL 5.7 or higher (or MariaDB equivalent)
    • Web server (Apache, Nginx, etc.)
    • Composer (for dependency management)
    • SSL Certificate (required for Stripe payments in production)
  2. Download & Extract:
    • Download the script and extract it to your web server's root directory (e.g., htdocs/AI-VOICE-STUDIO).
  3. Database Setup:
    • Create a MySQL database named e.g ai_voice_studio (or update DB_NAME in config.php)
    • Important: Import the included SQL file via cPanel phpMyAdmin or your preferred MySQL management tool:
      • database.sql - All database tables (users, subscriptions, transactions, audio_files, admin_settings, failed_payments, balance system, etc.)
    • Update database credentials in config.php (DB_HOST, DB_USER, DB_PASS)
    • The SQL file contains all necessary tables and is automatically created on first run if missing.
  4. Set Permissions:
    • Ensure the output/, temp/, saved_audio/, and assets/avatars/ directories are writable by the web server.
  5. Configure Web Server:
    • Point your server to the project folder. For local development, use http://localhost:3000 or your configured domain.

2. Configuration

All main settings are found in config.php. These control your site's branding, SEO, social links, email, analytics, ads, and page meta. Below is a detailed explanation of each configurable option before the /** Do not edit this section unless you know what you're doing. */ line.

Config NameDescriptionExample ValueHow to Customize
FAVICON_PATH Path to the favicon image shown in browser tabs. /assets/images/voice.png Replace the image file and update the path if needed.
SITE_NAME Your website's name, shown in titles and headers. AI Voice Studio Change to your brand or project name.
SITE_URL Main URL of your site (used for links and redirects). http://localhost:3000 Set to your live domain (e.g., https://yourdomain.com).
SITE_DESCRIPTION Meta description for SEO and social sharing. 100% free AI Text to speech Generator... Write a concise, attractive summary for your site.
SITE_KEYWORDS Comma-separated keywords for SEO. AI, Text to Speech, TTS, ... Add or remove keywords to target your audience.
SITE_AUTHOR Author or team name for meta tags. AI Voice Studio Team Update to your name or organization.
SITE_COPYRIGHT Copyright notice for your site footer. © 2025 237Coders All rights reserved. Update year and name as needed.
SOCIAL_FACEBOOK Facebook page URL for social icon. https://facebook.com/yourpage Replace with your actual Facebook page link.
SOCIAL_TWITTER Twitter profile URL for social icon. https://twitter.com/yourpage Replace with your actual Twitter profile link.
SOCIAL_INSTAGRAM Instagram profile URL for social icon. https://instagram.com/yourpage Replace with your actual Instagram profile link.
SOCIAL_LINKEDIN LinkedIn company page URL for social icon. https://linkedin.com/company/yourpage Replace with your actual LinkedIn page link.
SOCIAL_YOUTUBE YouTube channel URL for social icon. https://youtube.com/yourpage Replace with your actual YouTube channel link.
SMTP_HOST SMTP server for sending emails (contact forms, notifications). smtp.example.com Use your email provider's SMTP server (e.g., smtp.gmail.com).
SMTP_USER SMTP username (usually your email address). [email protected] Enter your email account for sending mail.
SMTP_PASS SMTP password for authentication. yourpassword Enter your email password or app password.
SMTP_SECURE Encryption type for SMTP (tls or ssl). tls Choose tls for most providers, ssl for older servers.
SMTP_PORT Port for SMTP server (587 for TLS, 465 for SSL). 587 Set according to your SMTP provider's requirements.
SMTP_FROM Email address shown as sender. [email protected] Should match your SMTP_USER for best results.
SMTP_TO Default recipient for contact form messages. [email protected] Set to your support or admin email.
GOOGLE_ANALYTICS_ID Google Analytics tracking ID for site analytics. G-XXXXXXXXXX Get your ID from Google Analytics and paste here.
PRIVACY_PAGE_TITLE, PRIVACY_PAGE_DESCRIPTION Title and description for the privacy policy page. Privacy Policy, Learn about our privacy practices... Edit to match your site's privacy practices.
TERMS_PAGE_TITLE, TERMS_PAGE_DESCRIPTION Title and description for the terms of service page. Terms of Service, Review our terms of service... Edit to match your site's terms and agreements.
ABOUT_PAGE_TITLE, ABOUT_PAGE_DESCRIPTION Title and description for the about page. About Us, Discover the mission... Describe your team, mission, and vision.
ABOUT_PAGE_AVATAR1, ABOUT_PAGE_AVATAR2, ABOUT_PAGE_AVATAR3 Paths to avatar images for team members. assets/avatars/avatar1.png Replace images and update paths for your team.
TEAM_MEMBER1, TEAM_MEMBER1_ROLE (and 2, 3) Names and roles of team members for About page. Louis Tayoh, Lead Engineer Update with your actual team members and roles.
CONTACT_PAGE_TITLE, CONTACT_PAGE_DESCRIPTION Title and description for the contact page. Contact Us, Get in touch with us... Customize for your support or inquiry process.
RINGTONE_MAKER_META_TITLE, RINGTONE_MAKER_META_DESCRIPTION, RINGTONE_MAKER_META_KEYWORDS Meta tags for the ringtone maker tool page. Ringtone Maker - Cut audio music... Edit for SEO and clarity about your tool.
LYRICS_GENERATOR_META_TITLE, LYRICS_GENERATOR_META_DESCRIPTION, LYRICS_GENERATOR_META_KEYWORDS Meta tags for the lyrics generator tool page. AI Lyrics Generator Edit for SEO and clarity about your tool.
GEMINI_API_KEY API key for Gemini AI (used for lyrics generation and TTS). AIzaSyD7pHML5sPwZZvlZnszzXGCbJ8qojdwltU Replace with your own Gemini API key from Google AI Studio.
ASSEMBLYAI_API_KEY API key for AssemblyAI (used for speech-to-text transcription). 78d8d2d09d224629a8b1fa4c0b326879 Replace with your own AssemblyAI API key from AssemblyAI Dashboard.
CARTESIA_API_KEY API key for Cartesia (used for high-quality text-to-speech). sk_car_94jNBVE9CoSJUvU28Cza67 Replace with your own Cartesia API key from Cartesia Dashboard.
STRIPE_PUBLISHABLE_KEY Stripe public key for payment processing (client-side). pk_test_51HGe... Get from your Stripe Dashboard. Use test keys for development.
STRIPE_SECRET_KEY Stripe secret key for payment processing (server-side). sk_test_51HGe... Get from your Stripe Dashboard. Keep this secure!
USE_MOCK_PAYMENTS Enable mock payments for development (bypasses Stripe). false Set to true for development, false for production.
PAYPAL_CLIENT_ID PayPal Client ID for payment processing (client-side). AcBGnWJaBu6lZFFmavX-DHa1orFNYYYF-25f6Dw5vdCuSXmCKzRKMPO7XN4VG_Dm7djHCs1_xtFHUFN- Get from your PayPal Developer Dashboard. Create a REST API app.
PAYPAL_CLIENT_SECRET PayPal Client Secret for payment processing (server-side). EKPKUmdEJuE-39kGho8QmRrzlUqe62szOEKlLBM92pxrqYo3G-biOUS-DSDqGnSJptqLl6qP7MKIsKXV Get from your PayPal Developer Dashboard. Keep this secure!
PAYPAL_MODE PayPal environment mode. sandbox Use sandbox for testing, live for production.
CRON_SECRET Security key for protecting cron job endpoints. your_secure_secret_here Generate a secure random string for cron job authentication.
DB_HOST, DB_NAME, DB_USER, DB_PASS Database connection credentials. localhost, ai_voice_studio, etc. Update with your actual database credentials.
FREE_VOICES_LIMIT Number of voices available to free users. 10 Adjust based on your business model.
FREE_VOICES Array of voice names available to free users. ['Zephyr', 'Puck', ...] Modify array to change which voices are free.
AD_CODE HTML/JS code for ads, loaded from ads/ads_code.php if present. Dynamic (file contents) Edit ads/ads_code.php to add or change ad code.
Tip: For advanced customization, you can edit the PHP/HTML files directly (e.g., index.php, about-us.php, lyrics-generator.php, ringtone-maker.php, etc.) to change text, layout, or add new features.
All config options above are safe to edit and will not break the core logic of the application.

3. Customization

Site Content & Appearance

  • Edit assets/css/styles.css to change colors, fonts, and layout.
  • Replace images in assets/images/ and avatars in assets/avatars/ for a personalized look.
  • Update text and structure in PHP/HTML files for custom pages and features.

Voice Personas

  • Modify the $voicePersonas array in config.php to add, remove, or edit voice personas.
  • Each persona has a name, gender, description, avatar, and category.

Tools & Features

  • Text-to-Speech: Main feature on index.php. Users enter text, select a voice, and generate audio with premium voice restrictions.
  • Ringtone Maker: ringtone-maker.php lets users cut audio to create ringtones.
  • Lyrics Generator: ai-lyrics-generator.php uses AI to generate song lyrics based on prompts.
  • User Dashboard: dashboard.php provides overview of user activity, storage usage, and subscription status.
  • Account Management: account.php allows users to update profile information and change passwords.
  • Audio Library: my-audio.php lets premium users manage their saved audio files.
  • Subscription Plans: pricing.php displays available subscription tiers and features.
  • Admin Panel: Complete admin system for managing users, transactions, and settings.

User System

  • Registration/Login: auth/register.php and auth/login.php handle user authentication.
  • Free vs Premium: Free users get limited voice access and daily generation limits.
  • Storage Management: Premium users can save and organize their audio files.
  • Generation Limits: Configurable daily limits prevent abuse.

Payment System

  • Stripe Integration: Secure payment processing with subscription management.
  • Mock Payments: Development mode bypasses actual payment processing.
  • Subscription Plans: Flexible plan management through admin panel.
  • Transaction Tracking: Complete payment history and status tracking.

Meta & SEO

  • Edit meta titles, descriptions, and keywords in config.php for each tool/page.
  • Update SITE_KEYWORDS and SITE_DESCRIPTION for better SEO.

Ads Integration

  • Place your ad code in ads/ads_code.php. It will be loaded automatically if present.

SMTP & Email

  • Configure SMTP settings in config.php for contact forms and notifications.
  • Uses PHPMailer (see vendor/phpmailer/).

4. Advanced Customization

User System Configuration

  • Generation Limits: Configure daily limits for free and premium users in admin settings
  • Storage Limits: Set maximum storage per user type
  • Voice Access: Control which voices are available to free vs premium users
  • Audio Length Limits: Set maximum audio duration per generation

Stripe Webhook Setup

The webhook system provides reliable payment processing by handling Stripe events server-side instead of relying on frontend verification. This ensures payments are processed even if users close their browser or lose connection.

Webhook Endpoint

  • File: /api/stripe-webhook.php
  • Events Handled:
    • payment_intent.succeeded - Payment completed successfully
    • payment_intent.payment_failed - Payment failed
    • invoice.paid - Subscription invoice paid
    • invoice.payment_failed - Subscription payment failed
    • customer.subscription.created - New subscription
    • customer.subscription.updated - Subscription changes
    • customer.subscription.deleted - Subscription cancelled

Configuration Steps

  1. Configure Webhook Secret:
    • Open config.php
    • Find: define('STRIPE_WEBHOOK_SECRET', 'whsec_YOUR_WEBHOOK_SIGNING_SECRET_HERE');
    • Replace with your actual webhook secret from Stripe Dashboard
  2. Create Webhook in Stripe Dashboard:
    • Login to Stripe Dashboard
    • Go to Developers → Webhooks
    • Click "Add endpoint"
    • URL: https://your-domain.com/api/stripe-webhook.php
    • Select Events: All events listed above
    • Click "Add endpoint"
    • Copy the webhook signing secret (starts with whsec_)
    • Update your config.php with the real secret

Testing Webhooks

  • Stripe CLI (Recommended):
    stripe login
    stripe listen --forward-to localhost:8000/api/stripe-webhook.php
  • Ngrok (Local Testing):
    ngrok http 8000
    # Use the HTTPS URL in Stripe Dashboard
  • Test with Real Payment: Use Stripe test mode

Production Deployment

  1. Deploy code to production server
  2. Update Stripe webhook URL to production URL
  3. Switch to live Stripe keys
  4. Test with real payment in live mode

PayPal Integration Setup

AI Voice Studio supports PayPal payments as an alternative to Stripe. PayPal integration provides secure payment processing with subscription management.

Getting PayPal Credentials - Step by Step

Follow these detailed steps to create your PayPal developer account and get the required API credentials:

Step 1: Create PayPal Developer Account
  1. Go to https://developer.paypal.com/
  2. Click "Sign Up for Free" if you don't have an account
  3. Sign in with your existing PayPal business account, or create a new PayPal business account
  4. Important: You need a PayPal Business account for live payments. Personal accounts can only be used for sandbox testing
  5. Complete the account verification process
Step 2: Access Developer Dashboard
  1. After signing in, you'll be taken to the PayPal Developer Dashboard
  2. In the top navigation, click on "My Apps & Credentials"
  3. You'll see two main sections: Sandbox and Live
Step 3: Create Sandbox App (for Testing)
  1. Under the "Sandbox" section, click "Create App"
  2. Select "Merchant" as the app type
  3. Enter an "App Name" (e.g., "AI Voice Studio Sandbox")
  4. Click "Create App"
  5. After creation, you'll see your Sandbox Client ID and Sandbox Secret
  6. Copy and save these credentials - you'll use them for testing
Step 4: Create Live App (for Production)
  1. Switch to the "Live" section
  2. Click "Create App"
  3. Select "Merchant" as the app type
  4. Enter an "App Name" (e.g., "AI Voice Studio")
  5. Click "Create App"
  6. Important: Live apps require a verified PayPal Business account
  7. After creation, you'll get your Live Client ID and Live Secret
  8. Copy and save these credentials securely - these are for real payments
Step 5: Configure App Features
  1. In your app settings, ensure these features are enabled:
    • Accept Payments - Required for processing payments
    • Subscriptions - Required for recurring payments
    • Express Checkout - For streamlined checkout
  2. Review and accept PayPal's terms of service
Step 6: Get Your Credentials Summary

After completing the above steps, you should have:

  • Sandbox Client ID: Starts with "AZ..." (for testing)
  • Sandbox Client Secret: Starts with "EJ..." (for testing)
  • Live Client ID: Starts with "AZ..." (for production)
  • Live Client Secret: Starts with "EJ..." (for production)
Security Warning:
  • Never share your Client Secret publicly
  • Use Sandbox credentials for all development and testing
  • Only switch to Live credentials when ready for production
  • Store credentials securely and rotate them periodically
Step 7: Configure in Your Application
  1. Open your config.php file
  2. Update the PayPal settings:
    // For Development/Testing
    define('PAYPAL_CLIENT_ID', 'AZ...your_sandbox_client_id...');
    define('PAYPAL_CLIENT_SECRET', 'EJ...your_sandbox_client_secret...');
    define('PAYPAL_MODE', 'sandbox');
    
    // For Production (change when ready)
    define('PAYPAL_CLIENT_ID', 'AZ...your_live_client_id...');
    define('PAYPAL_CLIENT_SECRET', 'EJ...your_live_client_secret...');
    define('PAYPAL_MODE', 'live');
  3. Set PAYMENT_PROVIDER to 'paypal' if you want to use PayPal as default

Configuration Steps

After obtaining your PayPal credentials, configure them in your application:

  1. Update config.php:
    • Open config.php in your project root
    • Locate the PayPal configuration section
    • Replace the placeholder values with your actual credentials:
      define('PAYPAL_CLIENT_ID', 'AZ...your_client_id_here...');
      define('PAYPAL_CLIENT_SECRET', 'EJ...your_client_secret_here...');
      define('PAYPAL_MODE', 'sandbox'); // Change to 'live' for production
  2. Set Payment Provider:
    • Change PAYMENT_PROVIDER to 'paypal' to use PayPal as default
    • Options: 'stripe', 'paypal', 'mock'
  3. Test Configuration:
    • Start with sandbox mode for testing
    • Switch to live mode only after thorough testing
    • Verify payments work in your application

Testing PayPal Integration

  • Sandbox Testing:
    • Use sandbox mode for all testing
    • Create test buyer/seller accounts in PayPal Developer Dashboard
    • Test with small amounts to verify the integration works
  • Go Live:
    • Switch to live credentials when ready
    • Verify your PayPal business account is approved for payments
    • Test with real payments using small amounts first
PayPal vs Stripe: Both payment providers are fully supported. PayPal may be preferred in regions where Stripe is not available, or by users who prefer PayPal's interface. You can offer both options or choose one based on your target audience.

Monitoring & Logging

  • Successful webhook events logged
  • Failed signature verifications logged
  • Payment processing results logged
  • Error details available for debugging

Failed Payment Recovery System

The Failed Payment System provides comprehensive handling of payment failures with automatic retry logic, user notifications, and administrative oversight. This ensures maximum revenue recovery and excellent user experience.

Key Features

  • Automatic Failure Detection: Webhook-based detection of failed payments with detailed failure reasons
  • Retry Logic: Configurable retry attempts (default: 3) with configurable intervals (default: 24 hours)
  • User Notifications: Email alerts for failures, retry reminders, and success confirmations
  • Admin Dashboard: Monitor failed payments, view statistics, and process bulk retries
  • Security: Secure retry links with 24-hour expiration and one-time use tokens

Database Tables

  • failed_payments: Tracks all failed payment attempts with retry logic
    • stripe_payment_intent_id - Stripe payment identifier
    • retry_count - Number of retry attempts made
    • max_retries - Maximum retries allowed
    • next_retry_at - When next retry is scheduled
    • status - Current status (pending_retry, max_retries_reached, resolved, cancelled)
  • payment_notifications: Tracks all notifications sent to users
    • notification_type - Type of notification sent
    • email_sent - Whether email was sent successfully
    • in_app_shown - Whether shown in app
    • user_clicked - Whether user interacted

Configuration

Admin Settings (in admin_settings table):
  • payment_retry_enabled = 1 - Enable retry system
  • payment_retry_max_attempts = 3 - Max retry attempts
  • payment_retry_interval_hours = 24 - Hours between retries
  • payment_notification_enabled = 1 - Enable email notifications
  • payment_admin_notification = 1 - Send admin alerts
Config Constants (in config.php):
  • CRON_SECRET = 'your_secure_secret' - Cron job security
  • STRIPE_WEBHOOK_SECRET = 'whsec_...' - Webhook verification

API Endpoints

  • /api/failed-payment.php: Handles failed payment operations
    • get_user_failed_payments - Get user's failed payments
    • generate_retry_link - Generate secure retry link
    • process_retry_cron - Process retry attempts (cron only)
    • get_failed_payment_stats - Admin statistics
    • mark_payment_resolved - Mark payment as resolved

Cron Job Setup

File: /cron/process-failed-payments.php
Crontab Entry (every hour):
0 * * * * /usr/bin/php /path/to/project/cron/process-failed-payments.php
Web Cron Alternative:
curl -X POST https://yourdomain.com/cron/process-failed-payments.php \
  -d "cron_secret=your_secure_cron_secret_here"

User Experience Flow

  1. Payment Fails: Webhook receives payment_intent.payment_failed, failed payment record created, user receives immediate notification, admin receives alert
  2. Retry Process: System schedules retry, cron processes retries, user receives retry reminders
  3. User Actions: Dashboard shows failed payment alert, user can visit /failed-payments.php, generate retry links, complete payment manually
  4. Resolution: Payment succeeds via retry or manual completion, subscription activated, user receives success notification, failed payment marked as resolved

Notification Templates

  • Retry Reminder: "Payment Failed - Action Required" (includes retry link, expires in 24 hours)
  • Final Notice: "Final Notice - Payment Failed" (last chance notification)
  • Payment Resolved: "Payment Successful - Welcome to Premium!" (confirmation and next steps)

Admin Dashboard Integration

  • Failed Payment Statistics: $stats = $failedPaymentManager->getFailedPaymentStats(30);
  • Recent Failed Payments: Query failed_payments table joined with users and subscription_plans

Security Considerations

  • Webhook Security: Stripe signature verification required
  • Cron Job Security: Secret key required for web cron, IP whitelist recommended
  • Retry Link Security: Secure token generation, 24-hour expiration, one-time use tokens
  • User Authorization: Failed payments tied to user accounts, admin-only statistics access

Testing Failed Payments

Use these Stripe test card numbers to simulate failures:

  • 4000000000000002 - Generic decline
  • 4000000000009995 - Insufficient funds
  • 4000000000009987 - Lost card
Test Commands:
stripe listen --forward-to localhost:8000/api/stripe-webhook.php
stripe trigger payment_intent.payment_failed
Important: Always test the failed payment system thoroughly in development before deploying to production. Monitor logs and ensure notifications are working correctly.

Database Management

  • Auto-creation: Tables are created automatically on first run
  • Backup: Regular database backups recommended for user data
  • Migration: Update database credentials in config.php for migration

Admin Panel Access

  • Access admin panel at /admin.php
  • First registered user automatically becomes admin
  • Grant admin access through database: set role = 'admin' in users table
  • Admin can manage users, view analytics, and configure system settings

Editing PHP/HTML Files

You can directly edit the PHP/HTML files to:

  • Change page layouts, add new sections, or modify forms
  • Update static text, add new features, or integrate third-party services
  • Localize content for different languages
  • Customize email templates and notification messages

Adding New Voices

  1. Add new persona details to $voicePersonas in config.php
  2. Place the corresponding avatar image in assets/avatars/
  3. Add voice name to FREE_VOICES array if available to free users
  4. Update voice categories if needed

Audio & Storage Management

  • Format: Set 'audioFormat' in $appSettings to 'mp3' or 'wav'
  • Quality: Adjust 'sampleRate' for audio quality vs file size
  • Cleanup: Configure automatic cleanup of temporary files
  • Storage: Monitor saved_audio/ directory size for user files

Error Logging & Monitoring

  • Errors are logged to tts_errors.log in the project root if 'logErrors' is enabled
  • Monitor admin dashboard for system health and user activity
  • Set up email notifications for critical errors

5. Troubleshooting

Common Issues

  • Database Connection: Check MySQL credentials in config.php and ensure database exists.
  • Permissions: Ensure output/, temp/, saved_audio/, and assets/avatars/ are writable.
  • Dependencies: Run composer install if you see missing class errors.
  • API Key: Make sure GEMINI_API_KEY is valid and active from Google AI Studio, ASSEMBLYAI_API_KEY from AssemblyAI, and CARTESIA_API_KEY from Cartesia.
  • Stripe Issues: Verify STRIPE_PUBLISHABLE_KEY and STRIPE_SECRET_KEY are correct.

User System Issues

  • Login Problems: Check session configuration and database user table.
  • Registration Fails: Ensure email validation and unique constraints work.
  • Premium Access: Verify subscription status in database and Stripe dashboard.
  • Generation Limits: Check admin settings and user daily usage tracking.

Payment Issues

  • Test Mode: Use PayPal sandbox or Stripe test keys and test card numbers for development.
  • PayPal Setup: Ensure your PayPal app is properly configured in developer dashboard with correct permissions.
  • Stripe Webhooks: Set up Stripe webhooks to handle subscription events.
  • Mock Payments: Set USE_MOCK_PAYMENTS = true in config.php for development testing.
  • SSL Required: Stripe requires HTTPS in production. PayPal recommends HTTPS for security.
  • Webhook Verification: Ensure STRIPE_WEBHOOK_SECRET is configured for signature verification.
  • PayPal Permissions: Verify your PayPal app has permissions for payments and subscriptions.
  • Failed Payments: Check failed_payments table and webhook delivery logs in respective dashboards.

Failed Payment System Issues

  • Webhooks Not Received: Verify webhook endpoint URL in Stripe Dashboard and check server logs.
  • Retry Not Working: Check cron job setup and CRON_SECRET configuration.
  • Notifications Not Sent: Verify SMTP settings and check email delivery logs.
  • Database Errors: Ensure database.sql was imported correctly and contains all required tables.
  • Admin Stats Missing: Check failed payment manager class and database permissions.

Audio Generation Issues

  • Voice Access: Free users can only access first 10 voices defined in FREE_VOICES.
  • File Permissions: Check write permissions for audio output directories.
  • Storage Limits: Monitor user storage usage and limits.
  • API Limits: Check Gemini API quotas and usage limits, and Cartesia API limits.

Admin Panel Issues

  • Access Denied: First registered user becomes admin, or set role manually in database.
  • Stats Not Loading: Check database connections and admin functions.
  • Settings Not Saving: Verify admin permissions and database write access.

Email & SMTP Issues

  • SMTP Config: Double-check SMTP settings and credentials in config.php.
  • Gmail: Use app passwords instead of regular passwords for Gmail SMTP.
  • Port Issues: Try different ports (587 for TLS, 465 for SSL).

6. Updating & Installation Types

Important: AI Voice Studio has different update procedures depending on whether you're upgrading from the initial non-SaaS version or updating an existing SaaS installation. Follow the appropriate section below.

Installation Types Overview

  • Initial Non-SaaS Version: Basic version without database, user management, or premium features
  • SaaS Version: Full version with database, user subscriptions, admin panel, and premium features

Path A: Upgrading from Initial Non-SaaS Version to SaaS Version

If you have the initial non-SaaS version (without database) and want to upgrade to the full SaaS version, follow these steps:

  1. Backup Your Current Files:
    • Backup any custom modifications you've made to PHP/HTML files
    • Backup custom CSS, JS, or image files
    • Note any custom configurations you've made
  2. Download and Extract the Project:
    • Download the latest AI Voice Studio project files
    • Extract the main project to your web server directory (e.g., htdocs/ai-voice-studio)
  3. Create Database:
    • Create a new MySQL database (e.g., ai_voice_studio)
    • Import the database.sql file using phpMyAdmin or MySQL command line
    • Note your database credentials (host, name, username, password)
  4. Apply Update Files:
    • Locate the upload.zip file included with the project
    • Extract upload.zip directly into your installation root directory
    • Allow it to overwrite existing files when prompted
    • This adds all SaaS features, admin panel, user management, and premium functionality
  5. Configure Database Connection:
    • Open config.php in your installation root
    • Update database settings:
      define('DB_HOST', 'localhost');
      define('DB_NAME', 'ai_voice_studio'); // Your database name
      define('DB_USER', 'root'); // Your database username
      define('DB_PASS', ''); // Your database password
    • Configure other settings as needed (API keys, SMTP, etc.)
  6. Set Permissions:
    • Ensure these directories are writable by the web server:
      • output/
      • temp/
      • saved_audio/
      • assets/avatars/
  7. Complete Setup:
    • Access your site and register as the first user (automatically becomes admin)
    • Configure payment settings, API keys, and other options in the admin panel
    • Test all features including TTS, lyrics generator, and user management
Upgrade Notes:
  • This upgrade transforms your basic installation into a full SaaS platform
  • All original functionality is preserved while adding premium features
  • The update.zip contains all necessary files for the SaaS version
  • After upgrade, you'll have access to user management, subscriptions, and admin features

Path B: Updating Existing SaaS Version

If you already have the SaaS version installed and want to apply updates, follow these steps:

  1. Backup Your Installation:
    • Backup your config.php file (contains your API keys and settings)
    • Export your database (includes all user data, subscriptions, and transactions)
    • Backup the saved_audio/ directory (user-uploaded files)
    • Backup any custom modifications
  2. Download Update Package:
    • Download the update.zip file for your version
    • This contains only the changed files and any new features
  3. Apply Update:
    • Extract update.zip directly into your installation root directory
    • Overwrite existing files when prompted
    • The update preserves your existing configuration and data
  4. Run Database Update (if required):
    • Check if update.php exists in your root directory
    • If present, open update.php and update the database configuration at the top of the file:
      // Minimal database configuration - define only what we need
      if (!defined('DB_HOST')) {
          define('DB_HOST', 'localhost'); // Your database host
          define('DB_NAME', 'aivoicestudio'); // Your database name
          define('DB_USER', 'root'); // Your database username
          define('DB_PASS', ''); // Your database password
      }
    • Run the update by visiting https://yourdomain.com/update.php in your browser
    • This applies any necessary database schema changes
    • Delete update.php after successful execution for security
  5. Verify Update:
    • Test all features (TTS, lyrics, ringtone maker, STT)
    • Check admin panel and user management
    • Verify payment processing and webhooks
    • Confirm failed payment recovery system
SaaS Update Notes:
  • Updates are incremental and preserve your existing data
  • Always backup before updating, especially database and user files
  • The update.zip contains only modified files, not the entire project
  • Database updates are minimal and backward-compatible

Files Included in Updates

Upload.zip (for Non-SaaS to SaaS Upgrade):

  • Complete SaaS Files: All files needed to transform basic version to full SaaS
  • Admin System: Complete admin panel with user management, analytics, settings
  • User Management: Authentication, profiles, subscription management
  • Payment System: Stripe/PayPal integration, failed payment recovery
  • Database Schema: All tables for users, subscriptions, transactions, etc.
  • API Endpoints: Payment processing, webhooks, user actions
  • Enhanced Features: Premium voices, storage management, generation limits
  • Cron Jobs: Automated payment retry system

Update.zip (for SaaS Updates):

  • Modified Files: Only files that have been changed or fixed
  • Bug Fixes: Security patches, performance improvements, UI fixes
  • New Features: Additional functionality and enhancements
  • update.php: Database migration script (if needed)

Regular Maintenance

  • Dependencies: Run composer update periodically to update libraries
  • Database Backup: Regular backups of user data and transactions (include failed_payments tables)
  • File Cleanup: Monitor and clean temporary files in temp/ and output/
  • Storage Monitoring: Track user storage usage and system disk space
  • Failed Payment Monitoring: Review failed payment statistics and recovery rates in admin dashboard
  • Webhook Health: Monitor webhook delivery success in Stripe Dashboard

Security Updates

  • SSL Certificates: Keep SSL certificates updated for Stripe integration
  • API Keys: Rotate API keys periodically for security
  • Password Security: Monitor for weak passwords and enable 2FA if implemented
  • Admin Access: Regularly review admin user accounts

Performance Optimization

  • Database: Optimize database tables and add indexes as needed
  • Audio Files: Implement CDN for faster audio delivery
  • Caching: Add caching layers for better performance
  • Monitoring: Use admin dashboard to monitor system performance

Before Updating

  • Backup your config.php and custom files
  • Backup the entire database
  • Backup saved_audio/ directory
  • Test updates on staging environment first

7. Support & Credits

  • Developed by the AI Voice Studio Team
  • Contact: See contact-us.php for support
  • PHPMailer used for email functionality

8. License

This script is provided as-is. See vendor/phpmailer/README.md and LICENSE for third-party library licenses.

9. Customizing Text & Content

Tip: For best results, edit the text contents in the PHP/HTML files (e.g., index.php, about-us.php, etc.) to match your brand, style, and audience. This allows you to change page titles, descriptions, instructions, and more.
  • Open any PHP/HTML file in a text editor
  • Find and replace text as needed
  • Save and refresh your site to see changes

10. FAQ

How do I configure premium subscriptions?

Set up your Stripe or PayPal account, add your API keys to config.php, create subscription plans in the admin panel, and configure webhook endpoints. You can choose between Stripe or PayPal by setting the PAYMENT_PROVIDER in config.php.

Can free users access all features?

Free users have limited voice access (first 10 voices), daily generation limits, and cannot save audio files. Premium users get full access.

How do I manage user storage?

Premium users can save audio files in saved_audio/. Storage usage is tracked per user and can be monitored in the admin dashboard.

Can I use my own voices?

Yes, add new voice details in config.php voicePersonas array and upload corresponding avatar files to assets/avatars/.

How do I change the site logo or favicon?

Replace the image at assets/images/voice.png and update FAVICON_PATH in config.php.

How do I add new pages?

Duplicate an existing PHP file, rename it, and edit its contents. Update navigation in partials/nav.php if needed.

How do I enable/disable ads?

Edit or remove ads/ads_code.php. The ad code is loaded automatically if present.

How do I test payments without real money?

Set USE_MOCK_PAYMENTS = true in config.php for development testing, or use Stripe test mode with test card numbers, or PayPal sandbox environment for testing.

How do I access the admin panel?

Visit /admin.php and log in with an admin account. The first registered user automatically becomes an admin.

Can I limit daily generations for users?

Yes, configure generation limits in the admin settings. Different limits can be set for free and premium users.

How do I backup user data?

Backup your MySQL database regularly and the saved_audio/ directory which contains user uploaded audio files.

How does the failed payment recovery system work?

When payments fail, the system automatically creates retry attempts with email notifications. Users receive alerts in their dashboard and can manually retry payments. The system processes retries every 24 hours for up to 3 attempts by default.

How do I set up Stripe webhooks for payment recovery?

In your Stripe Dashboard, add a webhook endpoint pointing to https://yourdomain.com/api/stripe-webhook.php and select events: payment_intent.succeeded, payment_intent.payment_failed, invoice.payment_succeeded, invoice.payment_failed. Configure the webhook secret in config.php.

How do I configure the cron job for automated payment retries?

Set up a cron job to run php /path/to/project/cron/process-failed-payments.php every hour. Alternatively, use a web cron by calling https://yourdomain.com/cron/process-failed-payments.php with the proper CRON_SECRET.

Where can I monitor failed payments?

Visit /failed-payments.php as a user to see your own failed payments, or access the admin dashboard for system-wide statistics and bulk management of failed payments.

11. Contact & Feedback

For support, feature requests, or feedback, you can: