eleven_rb 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 80d8ceea950da279e7f35661aa4597eef9f6ff51fb67e38e607f634eaaa54feb
-  data.tar.gz: 8afa2939e1c267ee50c74ae2c6fe4fe8ea4f9fe0618ebb3d3cb52bc09f0c2683
+  metadata.gz: 8f8b7a2ab5d7ebe900552e83ae3e8499545f788da927ffc60d54185464d3bbc3
+  data.tar.gz: ee1b62923b6fc88304f4c78a60f68164617fd0f46d68cca09ad1496f14dda10d
 SHA512:
-  metadata.gz: 0cb196287b9bad7eafa9e34ac6b3c30933f9d9e316d42728fd9a609cb83db95e0b63d307568a8000bfcaf1613d059026c63ff83e75cd70e9c2f686874be72d0a
-  data.tar.gz: 22e29e9eab3a7e04a3ca040bf4cd564b70dd0077a777acbf095dc17eb5f64f3958578c457eb9f487c95a3194b7b62a9b97cf590bc8744c50f392c14af3532027
+  metadata.gz: 3079784a64fe6d3bff8e2c631d46763dcc6e352da16e9a7599d0ef0df7be45694c3b00279d3362f6459f7168c72f26b0e460eb80bd07239b675394979fd9cc59
+  data.tar.gz: 224530d093fdbd9b489adf6199cfd4cd19e22b2e9074bd42f59345fd0a5efcd06930c9ef9e9bfe9ab9034621c54eaf6c9443ba1b5aee91296c7365347fbcbe67

data/CHANGELOG.md

@@ -7,6 +7,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-02-08
+
+### Added
+
+- Music generation via `client.music.generate` (`POST /v1/music`)
+- Music streaming via `client.music.stream` (`POST /v1/music/stream`)
+- Composition plan creation via `client.music.create_plan` (`POST /v1/music/plan`)
+- `Client#generate_music` convenience method
+
 ## [0.2.0] - 2026-02-07
 
 ### Added

data/README.md

@@ -4,12 +4,13 @@
 [![CI](https://github.com/webventures/eleven_rb/actions/workflows/ci.yml/badge.svg)](https://github.com/webventures/eleven_rb/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-A Ruby client for the [ElevenLabs](https://try.elevenlabs.io/qyk2j8gumrjz) Text-to-Speech and Sound Effects API.
+A Ruby client for the [ElevenLabs](https://try.elevenlabs.io/qyk2j8gumrjz) Text-to-Speech, Sound Effects, and Music API.
 
 ## Features
 
 - Text-to-Speech generation and streaming
 - Sound effects generation from text descriptions
+- Music generation from prompts or composition plans
 - Voice management (list, get, create, update, delete)
 - Voice Library access (search 10,000+ community voices)
 - Voice Slot Manager for automatic slot management within account limits
@@ -109,6 +110,34 @@ audio = client.sound_effects.generate("gentle rain", loop: true)
 audio = client.generate_sound_effect("explosion")
 ```
 
+### Music
+
+```ruby
+# Generate music from a text prompt
+audio = client.music.generate("upbeat jazz piano solo")
+audio.save_to_file("jazz.mp3")
+
+# With options (duration, instrumental-only)
+audio = client.music.generate(
+  "epic orchestral battle theme",
+  music_length_ms: 30_000,
+  force_instrumental: true
+)
+
+# Using a composition plan (create_plan is free, no credits used)
+plan = client.music.create_plan("lo-fi hip hop beats", music_length_ms: 60_000)
+audio = client.music.generate(composition_plan: plan)
+audio.save_to_file("lo-fi.mp3")
+
+# Streaming
+File.open("song.mp3", "wb") do |file|
+  client.music.stream("ambient electronic") { |chunk| file.write(chunk) }
+end
+
+# Convenience method
+audio = client.generate_music("chill acoustic guitar")
+```
+
 ### Voice Management
 
 ```ruby

data/lib/eleven_rb/client.rb

@@ -86,6 +86,13 @@ module ElevenRb
       @sound_effects ||= Resources::SoundEffects.new(http_client)
     end
 
+    # Music generation resource
+    #
+    # @return [Resources::Music]
+    def music
+      @music ||= Resources::Music.new(http_client)
+    end
+
     # Voice slot manager
     #
     # @return [VoiceSlotManager]
@@ -112,6 +119,15 @@ module ElevenRb
       sound_effects.generate(text, **options)
     end
 
+    # Convenience method: generate music
+    #
+    # @param prompt [String] description of the music to generate
+    # @param options [Hash] additional options
+    # @return [Objects::Audio]
+    def generate_music(prompt, **options)
+      music.generate(prompt, **options)
+    end
+
     # Convenience method: stream speech
     #
     # @param text [String] the text to convert

data/lib/eleven_rb/resources/music.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+module ElevenRb
+  module Resources
+    # Music generation resource
+    #
+    # @example Generate music from a prompt
+    #   audio = client.music.generate("upbeat jazz piano solo")
+    #   audio.save_to_file("jazz.mp3")
+    #
+    # @example Generate music from a composition plan
+    #   plan = client.music.create_plan("epic orchestral battle theme", music_length_ms: 30_000)
+    #   audio = client.music.generate(composition_plan: plan)
+    #   audio.save_to_file("battle.mp3")
+    #
+    # @example Stream music
+    #   File.open("song.mp3", "wb") do |file|
+    #     client.music.stream("lo-fi hip hop beats") { |chunk| file.write(chunk) }
+    #   end
+    class Music < Base
+      DEFAULT_MODEL = 'music_v1'
+
+      # Generate music from a text prompt or composition plan
+      #
+      # @param prompt [String, nil] text description of the music to generate (mutually exclusive with composition_plan)
+      # @param composition_plan [Hash, nil] structured composition plan (mutually exclusive with prompt)
+      # @param music_length_ms [Integer, nil] duration in milliseconds (3000-600000, only with prompt)
+      # @param model_id [String] the model to use (default: music_v1)
+      # @param force_instrumental [Boolean, nil] whether to force instrumental output (only with prompt)
+      # @param respect_sections_durations [Boolean, nil] whether to respect section durations (only with compose)
+      # @param output_format [String] audio output format
+      # @return [Objects::Audio]
+      def generate(prompt = nil, composition_plan: nil, music_length_ms: nil,
+                   model_id: DEFAULT_MODEL, force_instrumental: nil,
+                   respect_sections_durations: nil, output_format: 'mp3_44100_128')
+        validate_prompt_or_plan!(prompt, composition_plan)
+
+        body = build_body(
+          prompt: prompt,
+          composition_plan: composition_plan,
+          music_length_ms: music_length_ms,
+          model_id: model_id,
+          force_instrumental: force_instrumental,
+          respect_sections_durations: respect_sections_durations
+        )
+
+        path = "/music?output_format=#{output_format}"
+        response = post_binary(path, body)
+
+        audio = Objects::Audio.new(
+          data: response,
+          format: output_format,
+          voice_id: nil,
+          text: prompt,
+          model_id: model_id
+        )
+
+        cost_info = Objects::CostInfo.new(text: prompt || '', voice_id: 'music', model_id: model_id)
+        http_client.config.trigger(
+          :on_audio_generated,
+          audio: audio,
+          voice_id: nil,
+          text: prompt,
+          cost_info: cost_info.to_h
+        )
+
+        audio
+      end
+
+      # Stream music from a text prompt or composition plan
+      #
+      # @param prompt [String, nil] text description of the music to generate
+      # @param composition_plan [Hash, nil] structured composition plan
+      # @param music_length_ms [Integer, nil] duration in milliseconds (3000-600000, only with prompt)
+      # @param model_id [String] the model to use
+      # @param force_instrumental [Boolean, nil] whether to force instrumental output (only with prompt)
+      # @param output_format [String] audio output format
+      # @yield [String] each chunk of audio data
+      # @return [void]
+      def stream(prompt = nil, composition_plan: nil, music_length_ms: nil,
+                 model_id: DEFAULT_MODEL, force_instrumental: nil,
+                 output_format: 'mp3_44100_128', &block)
+        validate_prompt_or_plan!(prompt, composition_plan)
+        raise ArgumentError, 'Block required for streaming' unless block_given?
+
+        body = build_body(
+          prompt: prompt,
+          composition_plan: composition_plan,
+          music_length_ms: music_length_ms,
+          model_id: model_id,
+          force_instrumental: force_instrumental
+        )
+
+        path = "/music/stream?output_format=#{output_format}"
+        post_stream(path, body, &block)
+
+        cost_info = Objects::CostInfo.new(text: prompt || '', voice_id: 'music', model_id: model_id)
+        http_client.config.trigger(
+          :on_audio_generated,
+          audio: nil,
+          voice_id: nil,
+          text: prompt,
+          cost_info: cost_info.to_h
+        )
+      end
+
+      # Create a composition plan from a text prompt (free, no credits used)
+      #
+      # @param prompt [String] text description of the music
+      # @param music_length_ms [Integer, nil] desired duration in milliseconds
+      # @param model_id [String] the model to use
+      # @return [Hash] structured composition plan
+      def create_plan(prompt, music_length_ms: nil, model_id: DEFAULT_MODEL)
+        validate_presence!(prompt, 'prompt')
+
+        body = {
+          prompt: prompt,
+          model_id: model_id
+        }
+        body[:music_length_ms] = music_length_ms unless music_length_ms.nil?
+
+        post('/music/plan', body)
+      end
+
+      private
+
+      def validate_prompt_or_plan!(prompt, composition_plan)
+        raise Errors::ValidationError, 'Either prompt or composition_plan must be provided' if prompt.nil? && composition_plan.nil?
+
+        return unless prompt && composition_plan
+
+        raise Errors::ValidationError, 'prompt and composition_plan are mutually exclusive'
+      end
+
+      def build_body(prompt:, composition_plan:, music_length_ms:, model_id:,
+                     force_instrumental: nil, respect_sections_durations: nil)
+        body = { model_id: model_id }
+
+        if prompt
+          body[:prompt] = prompt
+          body[:music_length_ms] = music_length_ms unless music_length_ms.nil?
+          body[:force_instrumental] = force_instrumental unless force_instrumental.nil?
+        else
+          body[:composition_plan] = composition_plan
+        end
+
+        body[:respect_sections_durations] = respect_sections_durations unless respect_sections_durations.nil?
+
+        body
+      end
+    end
+  end
+end

data/lib/eleven_rb/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ElevenRb
-  VERSION = '0.2.0'
+  VERSION = '0.3.0'
 end

data/lib/eleven_rb.rb

@@ -107,6 +107,7 @@ require_relative 'eleven_rb/resources/voice_library'
 require_relative 'eleven_rb/resources/models'
 require_relative 'eleven_rb/resources/user'
 require_relative 'eleven_rb/resources/sound_effects'
+require_relative 'eleven_rb/resources/music'
 
 # High-level components
 require_relative 'eleven_rb/voice_slot_manager'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: eleven_rb
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Web Ventures Ltd
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-02-07 00:00:00.000000000 Z
+date: 2026-02-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base64
@@ -156,6 +156,7 @@ files:
 - lib/eleven_rb/objects/voice_settings.rb
 - lib/eleven_rb/resources/base.rb
 - lib/eleven_rb/resources/models.rb
+- lib/eleven_rb/resources/music.rb
 - lib/eleven_rb/resources/sound_effects.rb
 - lib/eleven_rb/resources/text_to_speech.rb
 - lib/eleven_rb/resources/user.rb