🎵 ElevenLabs Music Generator

A web-based application for generating AI music using ElevenLabs' Music Generation API. This application provides both simple prompt-based music generation and advanced composition planning features.

🌟 Features

🎼 Two Generation Modes

• Simple Mode: Generate music directly from a text prompt
• Advanced Mode: Create detailed composition plans first, then generate music from those plans

🎛️ Advanced Controls

• Duration Control: Set music length from 10 seconds to 5 minutes (300 seconds)
• Composition Planning: Generate structured plans with styles, sections, and arrangements
• Real-time Preview: Built-in audio player with download capability
• Dark Mode: Toggle between light and dark themes

🔒 Enterprise Features

• SSO Authentication: Microsoft Azure AD integration (disabled for local development)
• Webhook Integration: Automatic provenance tracking for generated content
• Auto-cleanup: Generated files automatically deleted after 24 hours
• Error Handling: Comprehensive error reporting and logging

📋 Requirements

System Requirements

• PHP 7.4+ with cURL extension
• Web Server (Apache, Nginx, or PHP built-in server)
• ElevenLabs API Key with Music Generation access

ElevenLabs Subscription Requirements

• Music Generation Access: Requires special access and additional terms acceptance
• Recommended: Creator or Pro tier subscription
• Contact: Your ElevenLabs account team for music generation enablement

🚀 Installation

1. Clone the Repository

git clone https://bitbucket.org/zlalani/music-generation.git
cd music-generation

2. Configure API Key

Edit config.php and replace the API key:

return [
    'elevenlabs_api_key' => 'your-actual-api-key-here',
    'max_file_age_hours' => 24,
    'generated_files_dir' => 'generated/'
];

3. Set Permissions

# Create generated files directory
mkdir -p generated/
chmod 755 generated/

# Ensure PHP can write to the directory
chown www-data:www-data generated/ # On Ubuntu/Debian
# OR
chown apache:apache generated/     # On CentOS/RHEL

4. Local Development

For quick local testing:

# Using PHP built-in server
php -S localhost:8000

# Then visit: http://localhost:8000

🎯 Usage Guide

Simple Mode

1. Select "Simple Mode" from the dropdown
2. Enter your music description (e.g., "Upbeat electronic dance track with driving bass")
3. Optionally set duration using the slider (0 = auto-duration)
4. Click "Generate Music"
5. Wait for generation (may take 30-60 seconds)
6. Play and download your generated music

Advanced Mode

1. Select "Advanced Mode (with Composition Plan)"
2. Enter your music description
3. Click "Generate Composition Plan" first
4. Review the generated plan (includes styles, sections, structure)
5. Click "Generate Music" to create audio from the plan
6. Play and download your generated music

Example Prompts

• Electronic: "Energetic EDM track with heavy bass drops and soaring synths"
• Classical: "Peaceful piano melody with subtle string accompaniment"
• Ambient: "Atmospheric soundscape with ethereal pads and gentle rain sounds"
• Rock: "Driving rock anthem with powerful drums and electric guitar"

🔧 API Endpoints Used

Music Generation

• Endpoint: POST https://api.elevenlabs.io/v1/music
• Purpose: Generate music from prompts or composition plans
• Parameters:
  • prompt: Text description (max 2000 characters)
  • music_length_ms: Duration in milliseconds (10000-300000)
  • composition_plan: Advanced structured plan (optional)

Composition Planning

• Endpoint: POST https://api.elevenlabs.io/v1/music/plan
• Purpose: Create detailed composition plans
• Parameters:
  • prompt: Text description (max 2000 characters)
  • music_length_ms: Duration in milliseconds (optional)
• Note: This endpoint doesn't consume credits but is rate-limited

🏗️ Architecture

File Structure

music-generation/
├── index.php                    # Main application interface
├── config.php                  # Configuration settings
├── generate_plan.php           # Composition plan generation endpoint
├── webhook_processor_audio.php # Webhook integration for provenance
├── store_user_session.php      # SSO user session storage
├── clear_user_session.php      # SSO user session cleanup
├── generated/                  # Auto-generated music files (auto-cleanup)
└── README.md                   # This documentation

Key Components

Authentication System

• Microsoft SSO: Azure AD integration for enterprise use
• Local Override: Disabled for development/testing
• Session Management: Token-based authentication

Webhook Integration

• Provenance Tracking: Automatic logging of all generation events
• User Tracking: Captures SSO user information (email, name, ID)
• Enhanced Metadata: Generation mode, IP address, user agent
• Data Structure: Standardized webhook payload format
• Error Handling: Graceful fallback if webhook fails

File Management

• Auto-naming: Timestamped filename generation
• Auto-cleanup: Configurable file retention (default: 24 hours)
• Storage: Local filesystem with organized structure

🛠️ Configuration Options

config.php Settings

return [
    // ElevenLabs API configuration
    'elevenlabs_api_key' => 'your-api-key',
    
    // File management
    'max_file_age_hours' => 24,        # Auto-delete after 24 hours
    'generated_files_dir' => 'generated/' # Storage directory
];

Webhook Configuration

The AudioWebhookProcessor class supports:

• Custom webhook URLs
• Configurable timeouts
• SSL verification settings
• Client/user identification
• Deliverable tracking

🚨 Troubleshooting

Common Issues

"Music generation requires additional access"

• Cause: ElevenLabs Music API requires special access
• Solution: Contact your ElevenLabs account team
• Links: Music Terms

"Please configure your ElevenLabs API key"

• Cause: Invalid or missing API key in config.php
• Solution: Update config.php with valid API key

"API Error (403): limited_access"

• Cause: API key doesn't have music generation permissions
• Solution: Upgrade subscription and accept music terms

Files not generating

• Check: PHP error logs for detailed error messages
• Verify: Generated directory permissions (755)
• Ensure: Sufficient disk space available

Debug Mode

Enable PHP error reporting for development:

// Add to top of index.php for debugging
error_reporting(E_ALL);
ini_set('display_errors', 1);

🔐 Security Considerations

API Key Protection

• Store API keys securely in config.php
• Never commit API keys to version control
• Use environment variables in production

File Security

• Generated files are automatically cleaned up
• No sensitive data stored in generated files
• Directory permissions properly configured

SSO Integration

• Microsoft Azure AD integration available
• Token-based session management
• Configurable for enterprise environments

🚀 Deployment

Production Checklist

• Configure proper web server (Apache/Nginx)
• Set up HTTPS/SSL certificates
• Configure proper file permissions
• Enable SSO authentication
• Set up monitoring and logging
• Configure webhook endpoints
• Test music generation access
• Set up automated backups

Environment Variables

Consider using environment variables for sensitive config:

// In config.php
return [
    'elevenlabs_api_key' => $_ENV['ELEVENLABS_API_KEY'] ?? 'fallback-key',
    // ... other settings
];

📊 Monitoring & Analytics

Webhook Tracking

All generations are tracked via webhook with comprehensive metadata:

Standard Fields

• Generation timestamp: When the music was created
• User identification: SSO email, name, and user ID
• Prompt/settings used: Full generation parameters
• File information: Size, filename, duration
• Success/failure status: Generation outcome

Enhanced Tracking (Music Specific)

• Content type: "Music Generation"
• Generation mode: "Simple Prompt" or "Advanced (with Composition Plan)"
• Client identification: "Oliver Agency - Music Generation"
• Technical metadata: User agent, IP address
• API endpoint: "elevenlabs-music" for identification

Webhook Payload Example

{
  "prompt": "Upbeat electronic dance track",
  "generation_type": "ElevenLabs Music Generation",
  "client": "Oliver Agency - Music Generation",
  "user_email": "user@oliver.agency",
  "user_name": "John Doe",
  "settings": {...},
  "additional_data": {
    "content_type": "Music Generation",
    "generation_mode": "Simple Prompt",
    "filename": "music_2023-08-19_14-30-45.mp3",
    "file_size": 2048576,
    "ip_address": "192.168.1.100",
    "user_agent": "Mozilla/5.0..."
  }
}

File Management

• Automatic cleanup prevents disk space issues
• Configurable retention periods
• File size and generation tracking

🤝 Contributing

Development Setup

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

Code Standards

• Follow PHP PSR standards
• Comment complex functionality
• Test with both generation modes
• Verify webhook integration

📄 License

This project is proprietary software developed for Oliver Agency. All rights reserved.

🆘 Support

For Technical Issues

• Check the troubleshooting section above
• Review PHP error logs
• Test with the provided example prompts

For ElevenLabs API Issues

• Contact ElevenLabs support
• Review your subscription tier
• Check API key permissions

For Feature Requests

• Submit issues to the repository
• Include detailed requirements
• Provide use case examples

🔄 Version History

v1.0.0 - Initial Release

• Music generation with simple and advanced modes
• Composition plan generation
• Webhook integration for provenance tracking
• Dark mode support
• SSO authentication system
• Automatic file cleanup

---

Built with ❤️ using ElevenLabs Music Generation API