elevenlabs_client 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 244f4e543adab6725041a23c4742e95b32e6352635496ecf7ea3dbb7ae518d8b
+  data.tar.gz: 0f4444f50015137e1627a82edc7b9a6159a5dc4bdb41de521c8d2609130d642c
+SHA512:
+  metadata.gz: 4fda1901bc041645ef289c56bc1474ae9f5e3c9ec965dc70371271344b5412c799c8e9fb519d28d780b1c26de32b7318abc63b2d0d0681337fd004ec53e48179
+  data.tar.gz: 92dc43058342c80fd0c72d66d8936fac2d66f1a38c31d606481a40c244bc8c8cd1cfc452f959e1dc014b514c2a56135a40e103166c53d1cbd3c1d15e0f3849fd

data/CHANGELOG.md

@@ -0,0 +1,37 @@
+# Changelog
+
+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]
+
+### Added
+- Initial release of ElevenLabs Client gem
+- Support for ElevenLabs Dubbing API
+- Create dubbing jobs with video/audio files
+- Monitor dubbing job status
+- List dubbing jobs with filters
+- Retrieve dubbing resources for editing
+- Comprehensive error handling with specific exception types
+- Support for multiple target languages
+- Configurable API endpoint and authentication
+- Full test coverage with RSpec
+- WebMock integration for testing
+
+### Features
+- **Dubbing API**: Complete support for ElevenLabs dubbing workflow
+- **Error Handling**: Specific exceptions for different error conditions
+- **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

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 ElevenLabs Client
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,174 @@
+# ElevenlabsClient
+
+A Ruby client library for interacting with ElevenLabs APIs, including dubbing and voice synthesis.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'elevenlabs_client', path: 'lib/elevenlabs_client'
+```
+
+And then execute:
+
+    $ bundle install
+
+## Usage
+
+### Configuration
+
+#### Rails Initializer (Recommended for Rails apps)
+
+Create `config/initializers/elevenlabs_client.rb`:
+
+```ruby
+ElevenlabsClient::Settings.configure do |config|
+  config.properties = {
+    elevenlabs_base_uri: ENV["ELEVENLABS_BASE_URL"],
+    elevenlabs_api_key: ENV["ELEVENLABS_API_KEY"],
+  }
+end
+```
+
+Once configured this way, you can create clients without passing any parameters:
+
+```ruby
+client = ElevenlabsClient.new
+# Uses the configured settings automatically
+```
+
+#### Alternative Configuration Syntax
+
+You can also use the module-level configure method:
+
+```ruby
+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(
+  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"
+)
+```
+
+### Basic Usage
+
+```ruby
+require 'elevenlabs_client'
+
+# Create a client
+client = ElevenlabsClient.new
+
+# Create a dubbing job
+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
+  )
+  
+  puts "Dubbing job created: #{result['dubbing_id']}"
+end
+
+# Check dubbing status
+dub_details = client.dubs.get("dubbing_id_here")
+puts "Status: #{dub_details['status']}"
+
+# List all dubbing jobs
+dubs = client.dubs.list(dubbing_status: "dubbed")
+puts "Completed dubs: #{dubs['dubs'].length}"
+
+# Get dubbing resources (for editing)
+resources = client.dubs.resources("dubbing_id_here")
+puts "Audio files: #{resources['resources']['audio_files']}"
+```
+
+### Available Dubbing Methods
+
+The client provides access to all dubbing endpoints through the `client.dubs` interface:
+
+- `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
+
+## Supported Language Codes
+
+Common target languages include:
+- `es` - Spanish
+- `pt` - Portuguese
+- `fr` - French
+- `de` - German
+- `it` - Italian
+- `pl` - Polish
+- `ja` - Japanese
+- `ko` - Korean
+- `zh` - Chinese
+- `hi` - Hindi
+
+## Error Handling
+
+The client raises specific exceptions 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}"
+rescue ElevenlabsClient::ValidationError => e
+  puts "Validation error: #{e.message}"
+rescue ElevenlabsClient::APIError => e
+  puts "API error: #{e.message}"
+end
+```
+
+## Development
+
+After checking out the repo, run `bundle install` to install dependencies.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/elevenlabs_client/client.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "faraday/multipart"
+
+module ElevenlabsClient
+  class Client
+    DEFAULT_BASE_URL = "https://api.elevenlabs.io"
+
+    attr_reader :base_url, :api_key, :dubs
+
+    def initialize(api_key: nil, base_url: nil, api_key_env: "ELEVENLABS_API_KEY", base_url_env: "ELEVENLABS_BASE_URL")
+      @api_key = api_key || fetch_api_key(api_key_env)
+      @base_url = base_url || fetch_base_url(base_url_env)
+      @conn = build_connection
+      @dubs = Dubs.new(self)
+    end
+
+    # Makes an authenticated GET request
+    # @param path [String] API endpoint path
+    # @param params [Hash] Query parameters
+    # @return [Hash] Response body
+    def get(path, params = {})
+      response = @conn.get(path, params) do |req|
+        req.headers["xi-api-key"] = api_key
+      end
+
+      handle_response(response)
+    end
+
+    # Makes an authenticated POST request
+    # @param path [String] API endpoint path
+    # @param body [Hash, nil] Request body
+    # @return [Hash] Response body
+    def post(path, body = nil)
+      response = @conn.post(path) do |req|
+        req.headers["xi-api-key"] = api_key
+        req.body = body if body
+      end
+
+      handle_response(response)
+    end
+
+    # Makes an authenticated multipart POST request
+    # @param path [String] API endpoint path
+    # @param payload [Hash] Multipart payload
+    # @return [Hash] Response body
+    def post_multipart(path, payload)
+      response = @conn.post(path) do |req|
+        req.headers["xi-api-key"] = api_key
+        req.body = payload
+      end
+
+      handle_response(response)
+    end
+
+    # Helper method to create Faraday::Multipart::FilePart
+    # @param file_io [IO] File IO object
+    # @param filename [String] Original filename
+    # @return [Faraday::Multipart::FilePart]
+    def file_part(file_io, filename)
+      Faraday::Multipart::FilePart.new(file_io, mime_for(filename), filename)
+    end
+
+    private
+
+    def fetch_api_key(env_key = "ELEVENLABS_API_KEY")
+      # First try Settings, then ENV, then raise error
+      if Settings.properties&.dig(:elevenlabs_api_key)
+        Settings.elevenlabs_api_key
+      else
+        ENV.fetch(env_key) do
+          raise AuthenticationError, "#{env_key} environment variable is required but not set and Settings.properties[:elevenlabs_api_key] is not configured"
+        end
+      end
+    end
+
+    def fetch_base_url(env_key = "ELEVENLABS_BASE_URL")
+      # First try Settings, then ENV, then default
+      if Settings.properties&.dig(:elevenlabs_base_uri)
+        Settings.elevenlabs_base_uri
+      else
+        ENV.fetch(env_key, DEFAULT_BASE_URL)
+      end
+    end
+
+    def build_connection
+      Faraday.new(url: base_url) do |f|
+        f.request :multipart
+        f.request :url_encoded
+        f.response :json, content_type: /\bjson$/
+        f.adapter Faraday.default_adapter
+      end
+    end
+
+    def handle_response(response)
+      case response.status
+      when 200..299
+        response.body
+      when 401
+        raise AuthenticationError, "Invalid API key or authentication failed"
+      when 429
+        raise RateLimitError, "Rate limit exceeded"
+      when 400..499
+        raise ValidationError, response.body.inspect
+      else
+        raise APIError, "API request failed with status #{response.status}: #{response.body.inspect}"
+      end
+    end
+
+    def mime_for(filename)
+      ext = File.extname(filename).downcase
+      case ext
+      when ".mp4"  then "video/mp4"
+      when ".mov"  then "video/quicktime"
+      when ".avi"  then "video/x-msvideo"
+      when ".mkv"  then "video/x-matroska"
+      when ".mp3"  then "audio/mpeg"
+      when ".wav"  then "audio/wav"
+      when ".flac" then "audio/flac"
+      when ".m4a"  then "audio/mp4"
+      else "application/octet-stream"
+      end
+    end
+  end
+end

data/lib/elevenlabs_client/dubs.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module ElevenlabsClient
+  class Dubs
+    def initialize(client)
+      @client = client
+    end
+
+    # POST /v1/dubbing (multipart)
+    # Creates a new dubbing job
+    # 
+    # @param file_io [IO] The audio/video file to dub
+    # @param filename [String] Original filename 
+    # @param target_languages [Array<String>] Target language codes (e.g., ["es", "pt", "fr"])
+    # @param name [String, nil] Optional name for the dubbing job
+    # @param options [Hash] Additional options (drop_background_audio, use_profanity_filter, etc.)
+    # @return [Hash] Response containing dubbing job details
+    def create(file_io:, filename:, target_languages:, name: nil, **options)
+      payload = {
+        file: @client.file_part(file_io, filename),
+        mode: "automatic",
+        target_languages: target_languages,
+        name: name
+      }.compact.merge(options)
+
+      @client.post_multipart("/v1/dubbing", payload)
+    end
+
+    # GET /v1/dubbing/{id}
+    # Retrieves dubbing job details
+    #
+    # @param dubbing_id [String] The dubbing job ID
+    # @return [Hash] Dubbing job details
+    def get(dubbing_id)
+      @client.get("/v1/dubbing/#{dubbing_id}")
+    end
+
+    # GET /v1/dubbing
+    # Lists dubbing jobs
+    #
+    # @param params [Hash] Query parameters (dubbing_status, page_size, etc.)
+    # @return [Hash] List of dubbing jobs
+    def list(params = {})
+      @client.get("/v1/dubbing", params)
+    end
+
+    # GET /v1/dubbing/{id}/resources
+    # Retrieves dubbing resources for editing (if dubbing_studio: true was used)
+    #
+    # @param dubbing_id [String] The dubbing job ID
+    # @return [Hash] Dubbing resources
+    def resources(dubbing_id)
+      @client.get("/v1/dubbing/#{dubbing_id}/resources")
+    end
+
+    private
+
+    attr_reader :client
+  end
+end

data/lib/elevenlabs_client/errors.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module ElevenlabsClient
+  class Error < StandardError; end
+  class APIError < Error; end
+  class AuthenticationError < Error; end
+  class RateLimitError < Error; end
+  class ValidationError < Error; end
+end

data/lib/elevenlabs_client/settings.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module ElevenlabsClient
+  class Settings
+    class << self
+      attr_accessor :properties
+
+      def configure
+        self.properties ||= {}
+        yield(self) if block_given?
+      end
+
+      def elevenlabs_base_uri
+        properties&.dig(:elevenlabs_base_uri) || ENV["ELEVENLABS_BASE_URL"] || "https://api.elevenlabs.io"
+      end
+
+      def elevenlabs_api_key
+        properties&.dig(:elevenlabs_api_key) || ENV["ELEVENLABS_API_KEY"]
+      end
+
+      # Reset configuration (useful for testing)
+      def reset!
+        self.properties = {}
+      end
+    end
+  end
+end

data/lib/elevenlabs_client/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module ElevenlabsClient
+  VERSION = "0.1.0"
+end

data/lib/elevenlabs_client.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require_relative "elevenlabs_client/version"
+require_relative "elevenlabs_client/errors"
+require_relative "elevenlabs_client/settings"
+require_relative "elevenlabs_client/dubs"
+require_relative "elevenlabs_client/client"
+
+module ElevenlabsClient
+  class Error < StandardError; end
+
+  # Convenience method to create a new client
+  def self.new(**options)
+    Client.new(**options)
+  end
+
+  # Convenience method to configure the client
+  def self.configure(&block)
+    Settings.configure(&block)
+  end
+end

metadata

@@ -0,0 +1,154 @@
+--- !ruby/object:Gem::Specification
+name: elevenlabs_client
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Vitor Oliveira
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2025-09-13 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: faraday-multipart
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rspec-core
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: A Ruby client library for interacting with ElevenLabs dubbing and voice
+  synthesis APIs
+email:
+- vbrazo@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/elevenlabs_client.rb
+- lib/elevenlabs_client/client.rb
+- lib/elevenlabs_client/dubs.rb
+- lib/elevenlabs_client/errors.rb
+- lib/elevenlabs_client/settings.rb
+- lib/elevenlabs_client/version.rb
+homepage: https://github.com/vbrazo/elevenlabs_client
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/vbrazo/elevenlabs_client
+  source_code_uri: https://github.com/vbrazo/elevenlabs_client
+  changelog_uri: https://github.com/vbrazo/elevenlabs_client/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.16
+signing_key:
+specification_version: 4
+summary: Ruby client for ElevenLabs API
+test_files: []