elevenlabs 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c2b887df23210fbd0b7c0d2e75e667ffb46ab4c47400f8db1915b60b8984adca
+  data.tar.gz: 51287a55127cfa42b10d0e01a5463a6bd14db42bae6e6f16a36ee6884ba359a7
+SHA512:
+  metadata.gz: '048e8939495f6e7e25920c3bcf88d9b17779435f79f56df03f057a86eec7069211eafafce8fc329046121b6df764ef8e595f45c6e5068d546654e4b29593b517'
+  data.tar.gz: 9e72052b4ef1371c3ba9790df2716c9a3d55645f40b58c39295ef01fb0e7f26c6420517f7b8e65af9aa92c64f0222ca36077d92595818ac2c7f7576acaff37d9

data/README.md

@@ -0,0 +1,234 @@
+# Elevenlabs Ruby Gem
+
+[![Gem Version](https://badge.fury.io/rb/elevenlabs.svg)](https://badge.fury.io/rb/elevenlabs)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
+
+A **Ruby client** for the [ElevenLabs](https://elevenlabs.io/) **Text-to-Speech API**.  
+This gem provides an easy-to-use interface for:
+
+- **Listing available voices**
+- **Fetching details about a voice**
+- **Creating a custom voice** (with uploaded sample files)
+- **Editing an existing voice**
+- **Deleting a voice**
+- **Converting text to speech** and retrieving the generated audio
+
+All requests are handled via [Faraday](https://github.com/lostisland/faraday).
+
+---
+
+## Table of Contents
+
+- [Features](#features)
+- [Installation](#installation)
+- [Usage](#usage)
+  - [Basic Example](#basic-example)
+  - [Rails Integration](#rails-integration)
+    - [Store API Key in Rails Credentials](#store-api-key-in-rails-credentials)
+    - [Rails Initializer](#rails-initializer)
+    - [Controller Example](#controller-example)
+- [Endpoints](#endpoints)
+- [Error Handling](#error-handling)
+- [Development](#development)
+- [Contributing](#contributing)
+- [License](#license)
+
+---
+
+## Features
+
+- **Simple and intuitive API client** for ElevenLabs.
+- **Multipart file uploads** for training custom voices.
+- **Automatic authentication** via API key configuration.
+- **Error handling** with custom exceptions.
+- **Rails integration support** (including credentials storage).
+
+---
+
+## Installation
+
+Add the gem to your `Gemfile`:
+
+```ruby
+gem "elevenlabs", "~> 0.0.1"
+```
+Then run:
+```ruby
+bundle install
+```
+Or install it directly using:
+```ruby
+gem install elevenlabs
+```
+Usage
+Basic Example (Standalone Ruby)
+```ruby
+require "elevenlabs"
+
+# 1. Configure the gem globally (Optional)
+Elevenlabs.configure do |config|
+  config.api_key = "YOUR_API_KEY"
+end
+
+# 2. Initialize a client (will use configured API key)
+client = Elevenlabs::Client.new
+
+# 3. List available voices
+voices = client.list_voices
+puts voices # JSON response with voices
+
+# 4. Convert text to speech
+voice_id = "YOUR_VOICE_ID"
+text = "Hello from Elevenlabs!"
+audio_data = client.text_to_speech(voice_id, text)
+
+# 5. Save the audio file
+File.open("output.mp3", "wb") { |f| f.write(audio_data) }
+puts "Audio file saved to output.mp3"
+```
+Note: You can override the API key per request:
+```ruby
+client = Elevenlabs::Client.new(api_key: "DIFFERENT_API_KEY")
+```
+Rails Integration
+Store API Key in Rails Credentials
+1. Open your encrypted credentials:
+```ruby
+EDITOR=vim rails credentials:edit
+```
+
+2. Add the ElevenLabs API key:
+```ruby
+eleven_labs:
+  api_key: YOUR_SECURE_KEY
+```
+3. Save and exit. Rails will securely encrypt your API key.
+
+Rails Initializer
+Create an initializer file: config/initializers/elevenlabs.rb
+```ruby
+# config/initializers/elevenlabs.rb
+require "elevenlabs"
+
+Rails.application.config.to_prepare do
+  Elevenlabs.configure do |config|
+    config.api_key = Rails.application.credentials.dig(:eleven_labs, :api_key)
+  end
+end
+```
+Now you can simply call:
+```ruby
+client = Elevenlabs::Client.new
+```
+without manually providing an API key.
+
+Endpoints
+1. List Voices
+```ruby
+client.list_voices
+# => { "voices" => [...] }
+```
+2. Get Voice Details
+```ruby
+client.get_voice("VOICE_ID")
+# => { "voice_id" => "...", "name" => "...", ... }
+```
+3. Create a Custom Voice
+```ruby
+sample_files = [File.open("sample1.mp3", "rb")]
+client.create_voice("Custom Voice", sample_files, description: "My custom AI voice")
+# => JSON response with new voice details
+```
+4. Check if a voice is banned?
+```ruby
+sample_files = [File.open("trump.mp3", "rb")]
+client.create_voice("Donald Trump", sample_files, description: "My Trump Voice")
+  => {"voice_id"=>"<RETURNED_VOICE_ID>", "requires_verification"=>false}
+  trump= "<RETURNED_VOICE_ID>"
+  client.banned? trump
+=> true
+```
+5. Edit a Voice
+```ruby
+client.edit_voice("VOICE_ID", name: "Updated Voice Name")
+# => JSON response with updated details
+```
+6. Delete a Voice
+```ruby
+client.delete_voice("VOICE_ID")
+# => JSON response acknowledging deletion
+```
+7. Convert Text to Speech
+```ruby
+audio_data = client.text_to_speech("VOICE_ID", "Hello world!")
+File.open("output.mp3", "wb") { |f| f.write(audio_data) }
+```
+8 Stream Text to Speech
+stream from terminal
+```ruby
+Mac: brew install sox
+Linux: sudo apt install sox
+
+IO.popen("play -t mp3 -", "wb") do |audio_pipe| # Notice "wb" (write binary)
+  client.text_to_speech_stream("VOICE_ID", "Some text to stream back in chunks") do |chunk|
+    audio_pipe.write(chunk.b) # Ensure chunk is written as binary
+  end
+end
+```
+
+Error Handling
+When the API returns an error, the gem raises specific exceptions:
+
+Exception	Meaning
+Elevenlabs::BadRequestError	Invalid request parameters
+Elevenlabs::AuthenticationError	Invalid API key
+Elevenlabs::NotFoundError	Resource (voice) not found
+Elevenlabs::APIError	General API failure
+Example:
+
+```ruby
+begin
+  client.text_to_speech("INVALID_VOICE_ID", "Test")
+rescue Elevenlabs::AuthenticationError => e
+  puts "Invalid API key: #{e.message}"
+rescue Elevenlabs::NotFoundError => e
+  puts "Voice not found: #{e.message}"
+rescue Elevenlabs::APIError => e
+  puts "General error: #{e.message}"
+end
+```
+
+Development
+Clone this repository
+```bash
+git clone https://github.com/your-username/elevenlabs.git
+cd elevenlabs
+```
+Install dependencies
+```bash
+bundle install
+```
+Build the gem
+```bash
+gem build elevenlabs.gemspec
+```
+Install the gem locally
+```bash
+gem install ./elevenlabs-0.0.1.gem
+```
+Contributing
+Contributions are welcome! Please follow these steps:
+
+Fork the repository
+Create a feature branch (git checkout -b feature/my-new-feature)
+Commit your changes (git commit -am 'Add new feature')
+Push to your branch (git push origin feature/my-new-feature)
+Create a Pull Request describing your changes
+For bug reports, please open an issue with details.
+
+License
+This project is licensed under the MIT License. See the LICENSE file for details.
+
+⭐ Thank you for using the Elevenlabs Ruby Gem!
+If you have any questions or suggestions, feel free to open an issue or submit a Pull Request!
+

data/lib/elevenlabs/client.rb

@@ -0,0 +1,291 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "faraday/multipart"
+require "json"
+
+module Elevenlabs
+  class Client
+    BASE_URL = "https://api.elevenlabs.io"
+
+    # Note the default param: `api_key: nil`
+    def initialize(api_key: nil)
+      # If the caller doesn’t provide an api_key, use the gem-wide config
+      @api_key = api_key || Elevenlabs.configuration&.api_key
+
+      @connection = Faraday.new(url: BASE_URL) do |conn|
+        conn.request :url_encoded
+        conn.response :raise_error
+        conn.adapter Faraday.default_adapter
+      end
+    end
+
+    #####################################################
+    #                     Text-to-Speech                #
+    #    (POST /v1/text-to-speech/{voice_id})           #
+    #####################################################
+
+    # Convert text to speech and retrieve audio (binary data)
+    # Documentation: https://elevenlabs.io/docs/api-reference/text-to-speech/convert
+    #
+    # @param [String] voice_id - the ID of the voice to use
+    # @param [String] text - text to synthesize
+    # @param [Hash] options - optional TTS parameters
+    #   :model_id           => String   (e.g. "eleven_monolingual_v1" or "eleven_multilingual_v1")
+    #   :voice_settings     => Hash     (stability, similarity_boost, style, use_speaker_boost, etc.)
+    #   :optimize_streaming => Boolean  (whether to receive chunked streaming audio)
+    #
+    # @return [String] The binary audio data (usually an MP3).
+    def text_to_speech(voice_id, text, options = {})
+      endpoint = "/v1/text-to-speech/#{voice_id}"
+      request_body = { text: text }
+
+      # If user provided voice_settings, add them
+      if options[:voice_settings]
+        request_body[:voice_settings] = options[:voice_settings]
+      end
+
+      # If user specified a model_id, add it
+      request_body[:model_id] = options[:model_id] if options[:model_id]
+
+      # If user wants streaming optimization
+      headers = default_headers
+      if options[:optimize_streaming]
+        headers["Accept"] = "audio/mpeg"
+        headers["Transfer-Encoding"] = "chunked"
+      end
+
+      response = @connection.post(endpoint) do |req|
+        req.headers = headers
+        req.body = request_body.to_json
+      end
+
+      # Returns raw binary data (often MP3)
+      response.body
+    rescue Faraday::ClientError => e
+      handle_error(e)
+    end
+
+    #####################################################
+    #              Text-to-Speech-Stream                #
+    # (POST /v1/text-to-speech/{voice_id})/stream       #
+    #####################################################
+    def text_to_speech_stream(voice_id, text, options = {}, &block)
+      endpoint = "/v1/text-to-speech/#{voice_id}/stream?output_format=mp3_44100_128"
+      request_body = { text: text, model_id: options[:model_id] || "eleven_multilingual_v2" }
+
+      headers = default_headers
+      headers["Accept"] = "audio/mpeg"
+
+      response = @connection.post(endpoint, request_body.to_json, headers) do |req|
+        req.options.on_data = Proc.new do |chunk, _|
+          block.call(chunk) if block_given?
+        end
+      end
+
+      response
+    rescue Faraday::ClientError => e
+      handle_error(e)
+    end
+
+
+    #####################################################
+    #                     GET Voices                    #
+    #                  (GET /v1/voices)                 #
+    #####################################################
+
+    # Retrieves all voices associated with your Elevenlabs account
+    # Documentation: https://elevenlabs.io/docs/api-reference/voices
+    #
+    # @return [Hash] The JSON response containing an array of voices
+    def list_voices
+      endpoint = "/v1/voices"
+      response = @connection.get(endpoint) do |req|
+        req.headers = default_headers
+      end
+      JSON.parse(response.body)
+    rescue Faraday::ClientError => e
+      handle_error(e)
+    end
+
+    #####################################################
+    #                 GET a Single Voice                #
+    #               (GET /v1/voices/{voice_id})         #
+    #####################################################
+
+    # Retrieves details about a single voice
+    #
+    # @param [String] voice_id
+    # @return [Hash] Details of the voice
+    def get_voice(voice_id)
+      endpoint = "/v1/voices/#{voice_id}"
+      response = @connection.get(endpoint) do |req|
+        req.headers = default_headers
+      end
+      JSON.parse(response.body)
+    rescue Faraday::ClientError => e
+      handle_error(e)
+    end
+
+    #####################################################
+    #                Create a Voice                     #
+    #               (POST /v1/voices/add)               #
+    #####################################################
+
+    # Creates a new voice
+    # @param [String] name - name of the voice
+    # @param [File] samples - array of files to train the voice
+    # @param [Hash] options - additional parameters
+    #   :description => String
+    #
+    # NOTE: This method may require a multipart form request
+    #       if you are uploading sample audio files.
+    def create_voice(name, samples = [], options = {})
+      endpoint = "/v1/voices/add"
+
+      # Ensure Faraday handles multipart form data
+      mp_connection = Faraday.new(url: BASE_URL) do |conn|
+        conn.request :multipart
+        conn.response :raise_error
+        conn.adapter Faraday.default_adapter
+      end
+
+      # Build multipart form parameters
+      form_params = {
+        "name" => name,
+        "description" => options[:description] || ""
+      }
+
+      # Convert File objects to multipart upload format
+      sample_files = []
+      samples.each_with_index do |sample_file, i|
+        sample_files << ["files", Faraday::UploadIO.new(sample_file.path, "audio/mpeg")]
+      end
+
+      # Perform the POST request
+      response = mp_connection.post(endpoint) do |req|
+        req.headers["xi-api-key"] = @api_key
+        req.body = form_params.merge(sample_files.to_h)
+      end
+
+      JSON.parse(response.body)
+    rescue Faraday::ClientError => e
+      handle_error(e)
+    end
+
+
+    #####################################################
+    #                Edit a Voice                       #
+    #           (POST /v1/voices/{voice_id}/edit)       #
+    #####################################################
+    # Updates an existing voice
+    # @param [String] voice_id
+    # @param [Array<File>] samples
+    # @param [Hash] options
+    # options[:name] [String] name
+    # options[:description] [String] description
+     
+    def edit_voice(voice_id, samples = [], options = {})
+      endpoint = "/v1/voices/#{voice_id}/edit"
+
+      # Force text fields to be strings.
+      form_params = {
+        "name"        => options[:name].to_s,
+        "description" => (options[:description] || "").to_s
+      }
+
+      form_params["files[]"] = samples.map do |sample_file|
+        Faraday::UploadIO.new(sample_file.path, "audio/mpeg", File.basename(sample_file.path))
+      end
+
+      mp_connection = Faraday.new(url: BASE_URL) do |conn|
+        conn.request :multipart
+        conn.response :raise_error
+        conn.adapter Faraday.default_adapter
+      end
+
+      response = mp_connection.post(endpoint) do |req|
+        req.headers["xi-api-key"] = @api_key
+        req.body = form_params
+      end
+
+      JSON.parse(response.body)
+    rescue Faraday::ClientError => e
+      handle_error(e)
+    end
+
+    #####################################################
+    #                Delete a Voice                     #
+    #         (DELETE /v1/voices/{voice_id})            #
+    #####################################################
+
+    # Deletes a voice from your account
+    # @param [String] voice_id
+    # @return [Hash] response
+    def delete_voice(voice_id)
+      endpoint = "/v1/voices/#{voice_id}"
+      response = @connection.delete(endpoint) do |req|
+        req.headers = default_headers
+      end
+
+      JSON.parse(response.body)
+    rescue Faraday::ClientError => e
+      handle_error(e)
+    end
+
+    #####################################################
+    #                 Banned Voice Check                #
+    #####################################################
+    
+    # Checks safety control on a single voice for "BAN"
+    # 
+    # @param [String] voice_id 
+    # @return [Boolean]
+    def banned?(voice_id)
+      voice = get_voice(voice_id)
+      voice["safety_control"] == "BAN"
+    end
+
+    #####################################################
+    #                 Active Voice Check                #
+    #####################################################
+    
+    # Checks if a voice_id is in list_voices
+    #
+    # @param [String] voice_id
+    # @return [Boolean]
+    def active?(voice_id)
+      active_voices = list_voices["voices"].map{|voice| voice["voice_id"]}
+      voice_id.in?(active_voices)
+    end
+
+    private
+
+    # Common headers needed by Elevenlabs
+    def default_headers
+      {
+        "xi-api-key"   => @api_key,
+        "Content-Type" => "application/json"
+      }
+    end
+
+    # Error handling
+    def handle_error(exception)
+      status = exception.response[:status] rescue nil
+      body   = exception.response[:body]   rescue "{}"
+      error_info = JSON.parse(body) rescue {}
+
+      detail = error_info["detail"]
+      simple_message = detail.is_a?(Hash) ? detail["message"] || detail.to_s : detail.to_s
+
+      case status
+      when 400 then raise BadRequestError, simple_message
+      when 401 then raise AuthenticationError, simple_message
+      when 404 then raise NotFoundError, simple_message
+      else
+        raise APIError, simple_message
+      end
+    end
+  end
+end
+

data/lib/elevenlabs/errors.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Elevenlabs
+  class Error < StandardError; end
+  class APIError < Error; end
+  class AuthenticationError < Error; end
+  class NotFoundError < Error; end
+  class BadRequestError < Error; end
+  # ... add more as needed ...
+end
+

data/lib/elevenlabs.rb

@@ -0,0 +1,24 @@
+# lib/elevenlabs.rb
+# frozen_string_literal: true
+
+require_relative "elevenlabs/client"
+require_relative "elevenlabs/errors"
+
+module Elevenlabs
+  VERSION = "0.0.1"
+
+  # Optional global configuration
+  class << self
+    attr_accessor :configuration
+  end
+
+  def self.configure
+    self.configuration ||= Configuration.new
+    yield(configuration)
+  end
+
+  class Configuration
+    attr_accessor :api_key
+  end
+end
+

metadata

@@ -0,0 +1,62 @@
+--- !ruby/object:Gem::Specification
+name: elevenlabs
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- hackliteracy
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2025-02-24 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'
+description: This gem provides a convenient Ruby interface to the ElevenLabs TTS,
+  Voice Cloning, and Streaming endpoints.
+email:
+- hackliteracy@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/elevenlabs.rb
+- lib/elevenlabs/client.rb
+- lib/elevenlabs/errors.rb
+homepage: https://github.com/ktamulonis/elevenlabs
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.5'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.23
+signing_key:
+specification_version: 4
+summary: A Ruby client for the ElevenLabs Text-to-Speech API
+test_files: []