elevenlabs_client 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 244f4e543adab6725041a23c4742e95b32e6352635496ecf7ea3dbb7ae518d8b
-  data.tar.gz: 0f4444f50015137e1627a82edc7b9a6159a5dc4bdb41de521c8d2609130d642c
+  metadata.gz: d6c150778cecf2c843fc1b5492d1cfbaed14306f010b240557945c631b083fa1
+  data.tar.gz: 62ba8f400b1be939bfc5839b47a5e636a5e888d812b8eabc04c1ca26196c9c63
 SHA512:
-  metadata.gz: 4fda1901bc041645ef289c56bc1474ae9f5e3c9ec965dc70371271344b5412c799c8e9fb519d28d780b1c26de32b7318abc63b2d0d0681337fd004ec53e48179
-  data.tar.gz: 92dc43058342c80fd0c72d66d8936fac2d66f1a38c31d606481a40c244bc8c8cd1cfc452f959e1dc014b514c2a56135a40e103166c53d1cbd3c1d15e0f3849fd
+  metadata.gz: 9df813daf9c443428e92cd323b94f05fa0791ab046b34f5c0ddd12bc19654235888c98bc47299355e2b9c6bf5d5a417d0b639f59b6d0af16b86f5e3f700202ad
+  data.tar.gz: 50b4a3229dbd3f2e25c5614d5178d4b688c812d9a01181748879a8490a66df457e4fb24b3b6110d0e72e1def3e877072045e84fecb18b175128b1b18fb96e2ad

data/CHANGELOG.md

@@ -5,7 +5,233 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [0.3.0] - 2025-09-12
+
+### Added
+- **🎵 Music Generation API** - AI-powered music composition and streaming
+  - `client.music.compose(options)` - Generate music from text prompts
+  - `client.music.compose_stream(options, &block)` - Real-time music streaming
+  - `client.music.compose_detailed(options)` - Generate music with metadata
+  - `client.music.create_plan(options)` - Create structured composition plans
+- **🎭 Voice Management API** - Complete CRUD operations for individual voices
+  - `client.voices.get(voice_id)` - Get detailed voice information
+  - `client.voices.list()` - List all voices in account
+  - `client.voices.create(name, samples, **options)` - Create custom voices from audio samples
+  - `client.voices.edit(voice_id, samples, **options)` - Edit existing voices
+  - `client.voices.delete(voice_id)` - Delete voices from account
+  - `client.voices.banned?(voice_id)` - Check voice safety status
+  - `client.voices.active?(voice_id)` - Check voice availability
+- **📋 Enhanced Rakefile** - Comprehensive gem management and development tasks
+  - Build, install, push, and clean gem operations
+  - Development tools (linting, testing, security audit)
+  - Documentation generation and serving
+  - Release preparation and management
+  - Maintenance and cleanup tasks
+
+### Enhanced
+- **🚨 Consolidated Error Handling** - Unified error handling across all endpoints
+  - Merged `handle_response`, `handle_binary_response`, and `handle_streaming_response` into single method
+  - Enhanced error message extraction from JSON, nested objects, arrays, and plain text
+  - More specific error types: `BadRequestError`, `NotFoundError`, `UnprocessableEntityError`
+  - Better error messages extracted from actual API responses instead of generic fallbacks
+- **🔧 HTTP Client Improvements** - Added missing HTTP methods and consolidated functionality
+  - Added `delete` method for DELETE requests
+  - Enhanced `post_with_custom_headers` for flexible header management
+  - Consistent error handling across all HTTP methods (GET, POST, DELETE, multipart, binary, streaming)
+- **📚 Documentation Organization** - Comprehensive documentation for all new features
+  - [MUSIC.md](docs/MUSIC.md) - Complete music generation guide (570 lines)
+  - [VOICES.md](docs/VOICES.md) - Voice management documentation (519 lines)
+  - Enhanced README with music capabilities and updated feature list
+  - Professional Rails integration examples
+
+### New Error Classes
+- `ElevenlabsClient::BadRequestError` (400) - Invalid parameters or malformed requests
+- `ElevenlabsClient::NotFoundError` (404) - Resource not found
+- `ElevenlabsClient::UnprocessableEntityError` (422) - Valid request but invalid data
+
+### Music Generation Features
+- **🎼 Composition Styles** - Support for all major music genres
+  - Electronic: EDM, House, Techno, Ambient, Synthwave
+  - Orchestral: Classical, Film Score, Epic Orchestral
+  - Popular: Pop, Rock, Hip-Hop, Country, Folk
+  - Jazz & Blues: Traditional Jazz, Smooth Jazz, Blues
+  - World Music: Celtic, Medieval, New Age, Ethnic
+- **🎛️ Advanced Controls** - Detailed composition parameters
+  - Custom composition plans with sections, tempo, key, instruments
+  - Multiple output formats (MP3, WAV) with quality settings
+  - Music length control (5 seconds to 5 minutes)
+  - Model selection for different generation approaches
+- **📡 Streaming Support** - Real-time music generation and playback
+  - Chunk-based streaming for immediate playback
+  - Memory-efficient processing for long compositions
+  - WebSocket integration for live applications
+
+### Voice Management Features
+- **🎤 Voice Creation** - Create custom voices from audio samples
+  - Multiple sample upload support for better quality
+  - Voice metadata and labeling system
+  - Quality validation and optimization
+- **🔧 Voice Editing** - Modify existing voices
+  - Add new samples to improve voice quality
+  - Update voice metadata and descriptions
+  - Batch voice operations
+- **🔍 Voice Discovery** - Advanced voice management
+  - Search and filter voices by category, labels, quality
+  - Voice status checking (active, banned, available)
+  - Voice analytics and usage tracking
+
+### Rails Integration Examples
+- **[MusicController](examples/music_controller.rb)** - Complete music generation implementation
+  - Basic and advanced music generation endpoints
+  - Streaming music with real-time playback
+  - Composition planning and structured music creation
+  - Batch generation and music library management
+  - Interactive music generation with user preferences
+- **[VoicesController](examples/voices_controller.rb)** - Voice management implementation
+  - Full CRUD operations for voice management
+  - File upload handling for voice samples
+  - Voice search and filtering capabilities
+  - Batch voice operations and management workflows
+
+### Technical Improvements
+- **🧪 Comprehensive Testing** - Expanded test coverage
+  - **57 new music tests** (24 unit + 33 integration)
+  - **Enhanced error handling tests** across all endpoints
+  - **Total test coverage**: 300+ tests with consistent passing
+- **🏗️ Architecture Consolidation** - Cleaner codebase
+  - Removed duplicate error handling methods
+  - Consolidated HTTP response processing
+  - Enhanced error message extraction with fallback handling
+  - Improved code organization and maintainability
+- **📦 Release Management** - Professional release workflow
+  - Automated release preparation tasks
+  - Version management and changelog automation
+  - Security auditing and dependency management
+  - Documentation generation and validation
+
+### Breaking Changes
+- **Error Handling** - More specific error types may require catch block updates
+  ```ruby
+  # Before (v0.2.0)
+  rescue ElevenlabsClient::ValidationError => e
+    # Handle all 4xx errors
+  end
+  
+  # After (v0.3.0) - More specific handling
+  rescue ElevenlabsClient::BadRequestError => e
+    # Handle 400 Bad Request
+  rescue ElevenlabsClient::NotFoundError => e
+    # Handle 404 Not Found
+  rescue ElevenlabsClient::UnprocessableEntityError => e
+    # Handle 422 Unprocessable Entity
+  rescue ElevenlabsClient::ValidationError => e
+    # Handle other 4xx errors
+  end
+  ```
+
+### Migration Guide
+```ruby
+# New Music API Usage
+client = ElevenlabsClient.new
+
+# Generate music
+music_data = client.music.compose(
+  prompt: "Upbeat electronic dance track",
+  music_length_ms: 30000
+)
+
+# Stream music generation
+client.music.compose_stream(prompt: "Relaxing ambient") do |chunk|
+  # Process audio chunk in real-time
+end
+
+# Voice management
+voices = client.voices.list
+voice = client.voices.get("voice_id")
+
+# Create custom voice
+File.open("sample.mp3", "rb") do |sample|
+  voice = client.voices.create("My Voice", [sample])
+end
+```
+
+## [0.2.0] - 2025-09-12
+
+### Added
+- **Text-to-Speech API** - Convert text to natural-sounding speech with voice customization
+- **Text-to-Speech Streaming API** - Real-time audio streaming for live applications
+- **Text-to-Dialogue API** - Multi-speaker conversation generation
+- **Sound Generation API** - AI-generated sound effects and ambient audio
+- **Comprehensive Documentation** - Separate documentation files for each API endpoint
+- **Rails Integration Examples** - Complete controller examples for all endpoints
+- **Enhanced Configuration** - Flexible configuration with Settings module
+- **Streaming Support** - Real-time audio chunk processing with block callbacks
+- **Binary Response Handling** - Proper handling of audio data responses
+- **Query Parameter Support** - URL query parameters for API requests
+
+### Enhanced
+- **Endpoint Organization** - Moved all endpoints to dedicated `lib/elevenlabs_client/endpoints/` directory
+- **Client Architecture** - Separated HTTP client logic from endpoint-specific functionality
+- **Error Handling** - Enhanced error handling with streaming-specific exceptions
+- **Test Coverage** - Expanded test suite to 187+ tests covering all new functionality
+- **Configuration System** - Priority-based configuration (explicit > Settings > ENV)
+
+### Documentation
+- **Modular Documentation** - Split endpoint documentation into separate files:
+  - [DUBBING.md](docs/DUBBING.md) - Audio/video dubbing functionality
+  - [TEXT_TO_SPEECH.md](docs/TEXT_TO_SPEECH.md) - Text-to-speech conversion
+  - [TEXT_TO_SPEECH_STREAMING.md](docs/TEXT_TO_SPEECH_STREAMING.md) - Real-time streaming
+  - [TEXT_TO_DIALOGUE.md](docs/TEXT_TO_DIALOGUE.md) - Multi-speaker dialogues
+  - [SOUND_GENERATION.md](docs/SOUND_GENERATION.md) - Sound effect generation
+- **Improved README** - Streamlined main README with quick start guide
+- **Rails Examples** - Complete controller implementations for all endpoints
+- **Usage Examples** - Comprehensive examples for each API feature
+
+### New Endpoints
+- `client.text_to_speech.*` - Text-to-speech conversion with voice settings
+- `client.text_to_speech_stream.*` - Real-time streaming text-to-speech
+- `client.text_to_dialogue.*` - Multi-speaker dialogue generation
+- `client.sound_generation.*` - AI sound effect and ambient audio generation
+
+### New Features
+- **Voice Customization** - Stability, similarity boost, style controls
+- **Audio Formats** - Multiple output formats (MP3, PCM) with quality options
+- **Looping Audio** - Generate seamless looping sound effects
+- **Deterministic Generation** - Seed support for consistent results
+- **Batch Processing** - Multiple sound generation in single requests
+- **WebSocket Integration** - Real-time streaming to WebSocket connections
+- **File Format Support** - Enhanced support for various audio/video formats
+
+### Technical Improvements
+- **Modular Architecture** - Clean separation of concerns with endpoint classes
+- **HTTP Client Enhancement** - Added streaming, binary, and custom header support
+- **Settings Management** - Centralized configuration with Rails initializer support
+- **Memory Management** - Efficient handling of large audio files and streams
+- **Concurrent Testing** - Parallel test execution for faster development
+
+### Examples Added
+- `examples/dubs_controller.rb` - Complete dubbing workflow with batch processing
+- `examples/text_to_speech_controller.rb` - TTS with voice customization
+- `examples/streaming_audio_controller.rb` - Real-time streaming with WebSocket support
+- `examples/text_to_dialogue_controller.rb` - Specialized dialogue endpoints
+- `examples/sound_generation_controller.rb` - Sound effects with presets and batch processing
+- `examples/rails_initializer.rb` - Rails configuration example
+
+### Breaking Changes
+- **Endpoint Access** - Dubbing methods moved from `client.create_dub` to `client.dubs.create`
+- **File Structure** - Endpoint classes moved to `lib/elevenlabs_client/endpoints/`
+- **Configuration** - Enhanced configuration system with new precedence rules
+
+### Migration Guide
+```ruby
+# Before (v0.1.0)
+client.create_dub(file_io: file, filename: "video.mp4", target_languages: ["es"])
+
+# After (v0.2.0)
+client.dubs.create(file_io: file, filename: "video.mp4", target_languages: ["es"])
+```
+
+## [0.1.0] - 2025-09-12
 
 ### Added
 - Initial release of ElevenLabs Client gem
@@ -26,12 +252,4 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **File Support**: Multiple video and audio formats (MP4, MOV, MP3, WAV, etc.)
 - **Language Support**: Multiple target languages for dubbing
 - **Configuration**: Flexible API key and endpoint configuration
-- **Testing**: Comprehensive test suite with integration tests
-
-## [0.1.0] - 2025-01-XX
-
-### Added
-- Initial implementation of ElevenLabs Client
-- Basic dubbing functionality
-- Error handling and validation
-- Documentation and examples
+- **Testing**: Comprehensive test suite with integration tests

data/README.md

@@ -1,24 +1,48 @@
 # ElevenlabsClient
 
-A Ruby client library for interacting with ElevenLabs APIs, including dubbing and voice synthesis.
+[![Gem Version](https://badge.fury.io/rb/elevenlabs_client.svg)](https://badge.fury.io/rb/elevenlabs_client)
+
+A comprehensive Ruby client library for the ElevenLabs API, supporting voice synthesis, dubbing, dialogue generation, sound effects, and AI music composition.
+
+## Features
+
+🎙️ **Text-to-Speech** - Convert text to natural-sounding speech  
+🎬 **Dubbing** - Create dubbed versions of audio/video content  
+💬 **Dialogue Generation** - Multi-speaker conversations  
+🔊 **Sound Generation** - AI-generated sound effects and ambient audio  
+🎵 **Music Generation** - AI-powered music composition and streaming  
+🎨 **Voice Design** - Create custom voices from text descriptions  
+🎭 **Voice Management** - Create, edit, and manage individual voices  
+🤖 **Models** - List available models and their capabilities  
+📡 **Streaming** - Real-time audio streaming  
+⚙️ **Configurable** - Flexible configuration options  
+🧪 **Well-tested** - Comprehensive test coverage  
 
 ## Installation
 
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'elevenlabs_client', path: 'lib/elevenlabs_client'
+gem 'elevenlabs_client'
 ```
 
 And then execute:
 
-    $ bundle install
+```bash
+$ bundle install
+```
 
-## Usage
+Or install it yourself as:
+
+```bash
+$ gem install elevenlabs_client
+```
+
+## Quick Start
 
 ### Configuration
 
-#### Rails Initializer (Recommended for Rails apps)
+#### Rails Applications (Recommended)
 
 Create `config/initializers/elevenlabs_client.rb`:
 
@@ -26,149 +50,254 @@ Create `config/initializers/elevenlabs_client.rb`:
 ElevenlabsClient::Settings.configure do |config|
   config.properties = {
     elevenlabs_base_uri: ENV["ELEVENLABS_BASE_URL"],
-    elevenlabs_api_key: ENV["ELEVENLABS_API_KEY"],
+    elevenlabs_api_key: ENV["ELEVENLABS_API_KEY"]
   }
 end
 ```
 
-Once configured this way, you can create clients without passing any parameters:
+Set your environment variables:
 
-```ruby
-client = ElevenlabsClient.new
-# Uses the configured settings automatically
+```bash
+export ELEVENLABS_API_KEY="your_api_key_here"
+export ELEVENLABS_BASE_URL="https://api.elevenlabs.io"  # Optional, defaults to official API
 ```
 
-#### Alternative Configuration Syntax
-
-You can also use the module-level configure method:
+#### Direct Configuration
 
 ```ruby
+# Module-level configuration
 ElevenlabsClient.configure do |config|
   config.properties = {
     elevenlabs_base_uri: "https://api.elevenlabs.io",
     elevenlabs_api_key: "your_api_key_here"
   }
 end
-```
-
-#### Configuration Precedence
-
-The client uses the following precedence order for configuration:
-
-1. **Explicit parameters** passed to `Client.new` (highest priority)
-2. **Settings.properties** configured via initializer
-3. **Environment variables** (lowest priority)
-
-This allows you to set defaults in your initializer while still being able to override them when needed.
-
-### Client Initialization
-
-There are several ways to create a client:
 
-```ruby
-# Using environment variables (default behavior)
-client = ElevenlabsClient.new
-
-# Passing API key directly
-client = ElevenlabsClient::Client.new(api_key: "your_api_key_here")
-
-# Custom base URL
-client = ElevenlabsClient::Client.new(
+# Or pass directly to client
+client = ElevenlabsClient.new(
   api_key: "your_api_key_here",
-  base_url: "https://custom-api.elevenlabs.io"
-)
-
-# Custom environment variable names
-client = ElevenlabsClient::Client.new(
-  api_key_env: "MY_CUSTOM_API_KEY_VAR",
-  base_url_env: "MY_CUSTOM_BASE_URL_VAR"
+  base_url: "https://api.elevenlabs.io"
 )
 ```
 
 ### Basic Usage
 
 ```ruby
-require 'elevenlabs_client'
-
-# Create a client
+# Initialize client (uses configured settings)
 client = ElevenlabsClient.new
 
-# Create a dubbing job
+# Text-to-Speech
+audio_data = client.text_to_speech.convert("21m00Tcm4TlvDq8ikWAM", "Hello, world!")
+File.open("hello.mp3", "wb") { |f| f.write(audio_data) }
+
+# Dubbing
 File.open("video.mp4", "rb") do |file|
   result = client.dubs.create(
     file_io: file,
     filename: "video.mp4",
-    target_languages: ["es", "pt", "fr"],
-    name: "My Video Dub",
-    drop_background_audio: true,
-    use_profanity_filter: false
+    target_languages: ["es", "fr", "de"]
   )
-  
-  puts "Dubbing job created: #{result['dubbing_id']}"
 end
 
-# Check dubbing status
-dub_details = client.dubs.get("dubbing_id_here")
-puts "Status: #{dub_details['status']}"
+# Dialogue Generation
+dialogue = [
+  { text: "Hello, how are you?", voice_id: "voice_1" },
+  { text: "I'm doing great, thanks!", voice_id: "voice_2" }
+]
+audio_data = client.text_to_dialogue.convert(dialogue)
+
+# Sound Generation
+audio_data = client.sound_generation.generate("Ocean waves crashing on rocks")
 
-# List all dubbing jobs
-dubs = client.dubs.list(dubbing_status: "dubbed")
-puts "Completed dubs: #{dubs['dubs'].length}"
+# Voice Design
+design_result = client.text_to_voice.design("Warm, professional female voice")
+generated_voice_id = design_result["previews"].first["generated_voice_id"]
 
-# Get dubbing resources (for editing)
-resources = client.dubs.resources("dubbing_id_here")
-puts "Audio files: #{resources['resources']['audio_files']}"
+voice_result = client.text_to_voice.create(
+  "Professional Voice",
+  "Warm, professional female voice",
+  generated_voice_id
+)
+
+# List Available Models
+models = client.models.list
+fastest_model = models["models"].min_by { |m| m["token_cost_factor"] }
+puts "Fastest model: #{fastest_model['name']}"
+
+# Voice Management
+voices = client.voices.list
+puts "Total voices: #{voices['voices'].length}"
+
+# Create custom voice from audio samples
+File.open("sample1.mp3", "rb") do |sample|
+  voice = client.voices.create("My Voice", [sample], description: "Custom narrator voice")
+  puts "Created voice: #{voice['voice_id']}"
+end
+
+# Music Generation
+music_data = client.music.compose(
+  prompt: "Upbeat electronic dance track with synthesizers",
+  music_length_ms: 30000
+)
+File.open("generated_music.mp3", "wb") { |f| f.write(music_data) }
+
+# Streaming Text-to-Speech
+client.text_to_speech_stream.stream("voice_id", "Streaming text") do |chunk|
+  # Process audio chunk in real-time
+  puts "Received #{chunk.bytesize} bytes"
+end
 ```
 
-### Available Dubbing Methods
+## API Documentation
 
-The client provides access to all dubbing endpoints through the `client.dubs` interface:
+### Core APIs
 
-- `client.dubs.create(file_io:, filename:, target_languages:, **options)` - Create a new dubbing job
-- `client.dubs.get(dubbing_id)` - Get dubbing job details
-- `client.dubs.list(params = {})` - List dubbing jobs with optional filters
-- `client.dubs.resources(dubbing_id)` - Get dubbing resources for editing
+- **[Dubbing API](docs/DUBBING.md)** - Create dubbed versions of audio/video content
+- **[Text-to-Speech API](docs/TEXT_TO_SPEECH.md)** - Convert text to natural speech
+- **[Text-to-Speech Streaming API](docs/TEXT_TO_SPEECH_STREAMING.md)** - Real-time audio streaming
+- **[Text-to-Dialogue API](docs/TEXT_TO_DIALOGUE.md)** - Multi-speaker conversations
+- **[Sound Generation API](docs/SOUND_GENERATION.md)** - AI-generated sound effects
+- **[Music Generation API](docs/MUSIC.md)** - AI-powered music composition and streaming
+- **[Text-to-Voice API](docs/TEXT_TO_VOICE.md)** - Design and create custom voices
+- **[Voice Management API](docs/VOICES.md)** - Manage individual voices (CRUD operations)
+- **[Models API](docs/MODELS.md)** - List available models and capabilities
 
-## Supported Language Codes
+### Available Endpoints
 
-Common target languages include:
-- `es` - Spanish
-- `pt` - Portuguese
-- `fr` - French
-- `de` - German
-- `it` - Italian
-- `pl` - Polish
-- `ja` - Japanese
-- `ko` - Korean
-- `zh` - Chinese
-- `hi` - Hindi
+| Endpoint | Description | Documentation |
+|----------|-------------|---------------|
+| `client.dubs.*` | Audio/video dubbing | [DUBBING.md](docs/DUBBING.md) |
+| `client.text_to_speech.*` | Text-to-speech conversion | [TEXT_TO_SPEECH.md](docs/TEXT_TO_SPEECH.md) |
+| `client.text_to_speech_stream.*` | Streaming TTS | [TEXT_TO_SPEECH_STREAMING.md](docs/TEXT_TO_SPEECH_STREAMING.md) |
+| `client.text_to_dialogue.*` | Dialogue generation | [TEXT_TO_DIALOGUE.md](docs/TEXT_TO_DIALOGUE.md) |
+| `client.sound_generation.*` | Sound effect generation | [SOUND_GENERATION.md](docs/SOUND_GENERATION.md) |
+| `client.music.*` | AI music composition and streaming | [MUSIC.md](docs/MUSIC.md) |
+| `client.text_to_voice.*` | Voice design and creation | [TEXT_TO_VOICE.md](docs/TEXT_TO_VOICE.md) |
+| `client.voices.*` | Voice management (CRUD) | [VOICES.md](docs/VOICES.md) |
+| `client.models.*` | Model information and capabilities | [MODELS.md](docs/MODELS.md) |
+
+## Configuration Options
+
+### Configuration Precedence
+
+1. **Explicit parameters** (highest priority)
+2. **Settings.properties** (configured via initializer)
+3. **Environment variables** (lowest priority)
+
+### Environment Variables
+
+- `ELEVENLABS_API_KEY` - Your ElevenLabs API key (required)
+- `ELEVENLABS_BASE_URL` - API base URL (optional, defaults to `https://api.elevenlabs.io`)
+
+### Custom Environment Variable Names
+
+```ruby
+client = ElevenlabsClient.new(
+  api_key_env: "CUSTOM_API_KEY_VAR",
+  base_url_env: "CUSTOM_BASE_URL_VAR"
+)
+```
 
 ## Error Handling
 
-The client raises specific exceptions for different error conditions:
+The client provides specific exception types for different error conditions:
 
 ```ruby
 begin
-  client.create_dub(...)
-rescue ElevenlabsClient::AuthenticationError => e
-  puts "Invalid API key: #{e.message}"
-rescue ElevenlabsClient::RateLimitError => e
-  puts "Rate limit exceeded: #{e.message}"
+  result = client.text_to_speech.convert(voice_id, text)
+rescue ElevenlabsClient::AuthenticationError
+  puts "Invalid API key"
+rescue ElevenlabsClient::RateLimitError
+  puts "Rate limit exceeded"
 rescue ElevenlabsClient::ValidationError => e
-  puts "Validation error: #{e.message}"
+  puts "Invalid parameters: #{e.message}"
 rescue ElevenlabsClient::APIError => e
   puts "API error: #{e.message}"
 end
 ```
 
+### Exception Types
+
+- `AuthenticationError` - Invalid API key or authentication failure
+- `RateLimitError` - Rate limit exceeded
+- `ValidationError` - Invalid request parameters
+- `APIError` - General API errors
+
+## Rails Integration
+
+The gem is designed to work seamlessly with Rails applications. See the [examples](examples/) directory for complete controller implementations:
+
+- [DubsController](examples/dubs_controller.rb) - Complete dubbing workflow
+- [TextToSpeechController](examples/text_to_speech_controller.rb) - TTS with error handling
+- [StreamingAudioController](examples/streaming_audio_controller.rb) - Real-time streaming
+- [TextToDialogueController](examples/text_to_dialogue_controller.rb) - Dialogue generation
+- [SoundGenerationController](examples/sound_generation_controller.rb) - Sound effects
+- [MusicController](examples/music_controller.rb) - AI music composition and streaming
+- [TextToVoiceController](examples/text_to_voice_controller.rb) - Voice design and creation
+- [VoicesController](examples/voices_controller.rb) - Voice management (CRUD operations)
+
 ## Development
 
-After checking out the repo, run `bundle install` to install dependencies.
+After checking out the repo, run:
+
+```bash
+bin/setup          # Install dependencies
+bundle exec rspec  # Run tests
+```
+
+To install this gem onto your local machine:
+
+```bash
+bundle exec rake install
+```
+
+To release a new version:
+
+1. Update the version number in `version.rb`
+2. Update `CHANGELOG.md`
+3. Run `bundle exec rake release`
+
+## Testing
+
+The gem includes comprehensive test coverage with RSpec:
+
+```bash
+# Run all tests
+bundle exec rspec
+
+# Run specific test files
+bundle exec rspec spec/elevenlabs_client/endpoints/
+bundle exec rspec spec/elevenlabs_client/client
+bundle exec rspec spec/integration/
+
+# Run with documentation format
+bundle exec rspec --format documentation
+```
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub.
+Bug reports and pull requests are welcome on GitHub at https://github.com/yourusername/elevenlabs_client.
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request
 
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for a detailed list of changes and version history.
+
+## Support
+
+- 📖 **Documentation**: [API Documentation](docs/)
+- 🐛 **Issues**: [GitHub Issues](https://github.com/yourusername/elevenlabs_client/issues)
+- 💬 **Discussions**: [GitHub Discussions](https://github.com/yourusername/elevenlabs_client/discussions)
+
+---
+
+Made with ❤️ for the Ruby community