flowspeech 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4aa33771a20fb9cb3f38ed4af5e46f47f6d884823a83c54e8d96c10fbe92f601
+  data.tar.gz: 3daec29ae0da53cf1931c3c4866847b717d068f443cc1ac056552b2ef661a616
+SHA512:
+  metadata.gz: 22522217c54774ae015a720d88a73a8f9fe18d8c465464d3fe08a2f1d65e7f77b8fae598567f6b6bd11efdf88561d2af317cb1b885c526f46c4ae2ea2d3d7284
+  data.tar.gz: b268e634167156062af46985c4af5df99aa2bf829152c84d2e8d86e41a84547f4a1b4d3df2a8463d637cffb2fff99240649c7ad08536983ff3a830a8f1df9121

data/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 FlowSpeech
+
+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,102 @@
+# FlowSpeech Ruby
+
+[![Gem Version](https://badge.fury.io/rb/flowspeech.svg)](https://rubygems.org/gems/flowspeech)
+[![Tests](https://github.com/waeckerlinfederowicz66-sketch/flowspeech-ruby/actions/workflows/test.yml/badge.svg)](https://github.com/waeckerlinfederowicz66-sketch/flowspeech-ruby/actions/workflows/test.yml)
+
+A small Ruby client for the [FlowSpeech text to speech API](https://flowspeech.io/). It supports context-aware synthesis, multi-speaker voice assignments, quota checks, audio metadata, and structured API errors.
+
+The gem uses only the Ruby standard library at runtime.
+
+## Installation
+
+Install the gem:
+
+```bash
+gem install flowspeech
+```
+
+Or add it to your Gemfile:
+
+```ruby
+gem "flowspeech", "~> 0.1"
+```
+
+Create a FlowSpeech API key, then keep it outside source control:
+
+```bash
+export FLOWSPEECH_API_KEY="your_api_key"
+```
+
+## Generate speech
+
+```ruby
+require "flowspeech"
+
+client = FlowSpeech::Client.new
+audio = client.synthesize(
+  text: "Welcome. [cheerfully] Let's make this sound natural.",
+  speakers: [{ voice_name: "Kore" }]
+)
+
+audio.write("speech.pcm")
+puts "#{audio.sample_rate} Hz, #{audio.num_channels} channel"
+```
+
+The API currently returns base64-encoded linear PCM with format metadata. The 
+`FlowSpeech::Audio#bytes` method returns the decoded bytes without changing the encoding.
+
+## Multi-speaker dialogue
+
+```ruby
+audio = client.synthesize(
+  text: "Host: Welcome to the show.\nGuest: Thanks for having me.",
+  speakers: [
+    { speaker: "Host", voice_name: "Charon" },
+    { speaker: "Guest", voice_name: "Kore" }
+  ]
+)
+```
+
+## Check quota
+
+```ruby
+quota = client.quota
+puts "#{quota.fetch("remaining")} characters remaining"
+```
+
+## Error handling
+
+```ruby
+begin
+  client.synthesize(text: "Hello")
+rescue FlowSpeech::APIError => error
+  warn "#{error.status}: #{error.message}"
+  warn "Retry after #{error.retry_after}s" if error.retryable
+end
+```
+
+## Development
+
+Run the tests without real credentials or network requests:
+
+```bash
+ruby -Ilib test/client_test.rb
+```
+
+Build the gem locally:
+
+```bash
+gem build flowspeech.gemspec
+```
+
+## Security
+
+- Never commit API keys.
+- Load `FLOWSPEECH_API_KEY` from the environment or a secret manager.
+- The client sends the key only in the `Authorization: Bearer` header.
+- Tests use an injected fake transport and contain no credentials.
+
+## License
+
+MIT
+

data/lib/flowspeech/client.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+require "base64"
+require "json"
+require "net/http"
+require "uri"
+
+module FlowSpeech
+  class Error < StandardError; end
+
+  class APIError < Error
+    attr_reader :status, :code, :error_code, :retryable, :retry_after
+
+    def initialize(message, status:, code: nil, error_code: nil, retryable: false, retry_after: nil)
+      super(message)
+      @status = status
+      @code = code
+      @error_code = error_code
+      @retryable = retryable
+      @retry_after = retry_after
+    end
+  end
+
+  class Audio
+    attr_reader :mime_type, :audio_base64, :quota, :sample_rate, :num_channels, :bits_per_sample
+
+    def initialize(data)
+      @mime_type = data.fetch("mimeType")
+      @audio_base64 = data.fetch("audioBase64")
+      @quota = data["quota"]
+      @sample_rate = data.fetch("sampleRate")
+      @num_channels = data.fetch("numChannels")
+      @bits_per_sample = data.fetch("bitsPerSample")
+    end
+
+    def bytes
+      Base64.strict_decode64(audio_base64)
+    rescue ArgumentError => e
+      raise Error, "FlowSpeech returned invalid base64 audio: #{e.message}"
+    end
+
+    def write(path)
+      File.binwrite(path, bytes)
+      path
+    end
+  end
+
+  class Client
+    DEFAULT_BASE_URL = "https://flowspeech.io"
+
+    def initialize(api_key: ENV["FLOWSPEECH_API_KEY"], base_url: DEFAULT_BASE_URL,
+                   open_timeout: 10, read_timeout: 90, transport: nil)
+      @api_key = api_key.to_s.strip
+      @base_url = URI(base_url)
+      @open_timeout = open_timeout
+      @read_timeout = read_timeout
+      @transport = transport
+
+      raise ArgumentError, "api_key is required" if @api_key.empty?
+      unless @base_url.is_a?(URI::HTTP) && @base_url.host
+        raise ArgumentError, "base_url must be an HTTP or HTTPS URL"
+      end
+    end
+
+    def quota
+      request(:get, "/api/ai/text-to-speech/quota").fetch("quota")
+    end
+
+    def synthesize(text:, speakers: [{ voice_name: "Kore" }], original_text: nil)
+      raise ArgumentError, "text is required" if text.to_s.strip.empty?
+
+      normalized_speakers = Array(speakers).map { |speaker| normalize_speaker(speaker) }
+      raise ArgumentError, "at least one speaker is required" if normalized_speakers.empty?
+
+      data = request(
+        :post,
+        "/api/ai/text-to-speech",
+        text: text,
+        originalText: original_text || text,
+        speakers: normalized_speakers
+      )
+      raise Error, "FlowSpeech response did not include audio" if data["audioBase64"].to_s.empty?
+
+      Audio.new(data)
+    end
+
+    private
+
+    def normalize_speaker(speaker)
+      input = speaker.respond_to?(:to_h) ? speaker.to_h : {}
+      voice_name = input[:voice_name] || input["voice_name"] || input[:voiceName] || input["voiceName"]
+      raise ArgumentError, "every speaker requires voice_name" if voice_name.to_s.strip.empty?
+
+      result = { voiceName: voice_name }
+      label = input[:speaker] || input["speaker"]
+      result[:speaker] = label unless label.to_s.strip.empty?
+      result
+    end
+
+    def request(method, path, payload = nil)
+      uri = @base_url + path
+      http_request = build_request(method, uri, payload)
+      response = @transport ? @transport.call(uri, http_request) : perform(uri, http_request)
+      parsed = parse_json(response.body)
+
+      unless response.code.to_i.between?(200, 299)
+        error_data = parsed["data"].is_a?(Hash) ? parsed["data"] : {}
+        message = parsed["message"].to_s.strip
+        message = "FlowSpeech request failed with HTTP #{response.code}" if message.empty?
+        raise APIError.new(
+          message,
+          status: response.code.to_i,
+          code: parsed["code"],
+          error_code: error_data["errorCode"],
+          retryable: error_data["retryable"] == true,
+          retry_after: response["Retry-After"]
+        )
+      end
+
+      unless parsed["code"] == 0 && parsed["data"].is_a?(Hash)
+        raise Error, parsed["message"].to_s.empty? ? "Unexpected FlowSpeech response" : parsed["message"]
+      end
+
+      parsed["data"]
+    end
+
+    def build_request(method, uri, payload)
+      request_class = method == :get ? Net::HTTP::Get : Net::HTTP::Post
+      request = request_class.new(uri)
+      request["Authorization"] = "Bearer #{@api_key}"
+      request["Accept"] = "application/json"
+      if payload
+        request["Content-Type"] = "application/json"
+        request.body = JSON.generate(payload)
+      end
+      request
+    end
+
+    def perform(uri, request)
+      Net::HTTP.start(
+        uri.host,
+        uri.port,
+        use_ssl: uri.scheme == "https",
+        open_timeout: @open_timeout,
+        read_timeout: @read_timeout
+      ) { |http| http.request(request) }
+    end
+
+    def parse_json(body)
+      JSON.parse(body.to_s)
+    rescue JSON::ParserError => e
+      raise Error, "FlowSpeech returned invalid JSON: #{e.message}"
+    end
+  end
+end
+

data/lib/flowspeech/version.rb

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

data/lib/flowspeech.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require_relative "flowspeech/version"
+require_relative "flowspeech/client"
+

metadata

@@ -0,0 +1,73 @@
+--- !ruby/object:Gem::Specification
+name: flowspeech
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: ruby
+authors:
+- FlowSpeech
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-08-04 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '12.3'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '14'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '12.3'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '14'
+description: Generate context-aware speech, multi-speaker dialogue, and audio metadata
+  with FlowSpeech.
+email:
+- support@flowspeech.io
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/flowspeech.rb
+- lib/flowspeech/client.rb
+- lib/flowspeech/version.rb
+homepage: https://flowspeech.io/
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://flowspeech.io/
+  source_code_uri: https://github.com/waeckerlinfederowicz66-sketch/flowspeech-ruby
+  changelog_uri: https://github.com/waeckerlinfederowicz66-sketch/flowspeech-ruby/releases
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.6.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Ruby client for the FlowSpeech text-to-speech API
+test_files: []