audd 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c61c509e3b3413538a3282945c8ddd9de46d730e060f4245aa9d7c53a3f77833
+  data.tar.gz: 5488664c79eac72e52993021ba29a8163482e9f91ddca9a2ca1a170f9156ac23
+SHA512:
+  metadata.gz: b87350f6c2823ecfc33da833f3ad5ac20adbcbf0b24396a784d8a53420517b1e735423f53e852e9286df23728550aa2021426c3088d9c92e99b21a387f84d57d
+  data.tar.gz: e4408ec839b591774d785eba13a8aa33780536af993fd8786bfcfdae2af032d3af547a23b35693e68b81b8a6ba82ebf00d2a75cedb324e198617f9f68a98225c

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.standard.yml

@@ -0,0 +1,3 @@
+# For available configuration options, see:
+#   https://github.com/standardrb/standard
+ruby_version: 3.1

data/CHANGELOG.md

@@ -0,0 +1,23 @@
+## [Unreleased]
+
+### Added
+
+- `Audd::Client#recognize` — the `POST api.audd.io/` recognition endpoint, via a
+  chainable request builder (`.return_metadata`, `.market`, `.timeout`) that sends
+  on `#execute!`. Takes a file path, `Pathname`, or `IO` as `file:`, or an https
+  url as `url:`.
+- Response objects named after the AudD OpenAPI schemas and namespaced under
+  `Audd`: `RecognitionResult`, `RecognizeSuccessResponse`, `ErrorResponse`,
+  `AppleMusicMetadata`, `SpotifyMetadata`, `DeezerMetadata`, `NapsterMetadata`
+  and `MusicBrainzEntry`. Unmapped keys stay reachable via `#[]` and `#raw`.
+- An exception hierarchy under `Audd::Error`, mapping every AudD error code to a
+  typed `Audd::ApiError` subclass and carrying the server's request echo.
+- A project-specific `User-Agent`: `audd-ruby/<version> ruby/<ruby version> (<platform>)`.
+- Contract tests running against the `AudDMusic/audd-openapi` spec and fixtures,
+  vendored as a submodule pinned to `v1.4.4`.
+
+`#recognize_enterprise` and `#find_lyrics` are stubbed and raise `NotImplementedError`.
+
+## [0.1.0] - 2026-08-26
+
+- Initial release

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,132 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+[INSERT CONTACT METHOD].
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Rowan McDonald
+
+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,173 @@
+# Audd
+
+Unofficial ruby sdk for AudD music recognition api. https://docs.audd.io/
+
+I've only implemented the parts of the api that I use, please open prs to contribute any additional functionality you would like.
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+```bash
+bundle add audd
+```
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+```bash
+gem install audd
+```
+
+## Usage
+
+
+### Recognize a song
+```ruby
+api_token = "your_token"
+audd = Audd.new(api_token)
+
+# read https://docs.audd.io/#recognize to learn about request options.
+request = audd.recognize(file: file) # one of file: file or url: url
+    .return_metadata(:apple_music, :musicbrainz, :spotify, :deezer)
+    .market("us")
+
+result = request.execute!
+```
+
+`file:` takes a path, a `Pathname`, or an open `IO`; `url:` takes an https url that
+AudD downloads itself. Pass exactly one of them.
+
+Nothing is sent until `execute!`, which returns an `Audd::RecognitionResult` — or
+`nil` when the audio was processed fine but didn't match anything. That is a
+successful response, not an error.
+
+```ruby
+result.title        #=> "Everybody Wants To Rule The World"
+result.artist       #=> "Tears For Fears"
+result.timecode     #=> "00:56" — where in the song the matched fragment plays
+result.apple_music  #=> Audd::AppleMusicMetadata
+result.public_match? #=> true (false for matches against your own catalog)
+```
+
+The response classes are plain objects named after the [AudD OpenAPI
+schemas](https://github.com/AudDMusic/audd-openapi), namespaced under `Audd`:
+`RecognitionResult`, `AppleMusicMetadata`, `SpotifyMetadata`, `DeezerMetadata`,
+`NapsterMetadata` and `MusicBrainzEntry`. Those schemas all allow extra
+properties and AudD passes provider payloads through verbatim, so any key the
+gem doesn't map is still reachable — `result.apple_music["hasLyrics"]` — and the
+whole payload is on `#raw`.
+
+Only `recognize` is implemented. `Audd::Client#recognize_enterprise` and
+`Audd::Client#find_lyrics` raise `NotImplementedError`.
+
+### Timeouts
+Because the recognize endpoint holds a long request open, the timeout for that endpoint is 60 seconds
+ - make sure not to make this request inside of an http transaction.
+
+Override it per request with `.timeout(seconds)`. On expiry you get an
+`Audd::TimeoutError`. Note that AudD meters the request server-side whether or
+not you wait for the answer.
+
+### Errors
+
+Everything raised descends from `Audd::Error`, so one `rescue` catches the lot:
+
+```
+Audd::Error
+├── Audd::ConfigurationError     # no api_token given and AUDD_API_TOKEN unset
+├── Audd::InvalidParameterError  # bad arguments — raised before anything is sent
+├── Audd::ConnectionError        # network, DNS, or TLS failure; nothing was received
+│   └── Audd::TimeoutError       # the request outran its timeout
+├── Audd::SerializationError     # a 2xx response whose body wasn't parseable JSON
+└── Audd::ApiError               # the server answered status: "error"
+    ├── Audd::AuthenticationError
+    ├── Audd::QuotaError
+    ├── Audd::SubscriptionError
+    ├── Audd::InvalidRequestError
+    ├── Audd::InvalidAudioError
+    ├── Audd::StreamLimitError
+    ├── Audd::RateLimitError
+    ├── Audd::NotReleasedError
+    ├── Audd::BlockedError
+    ├── Audd::NeedsUpdateError
+    └── Audd::ServerError
+```
+
+`Audd::ConfigurationError` and `Audd::InvalidParameterError` are raised locally,
+before any HTTP happens — a missing token, neither or both of `file:`/`url:`, an
+unreadable path, or a `return_metadata` source AudD doesn't accept.
+
+The rest of the hierarchy comes from the server. Each AudD error code maps to
+one class:
+
+| Code(s) | Class | Meaning |
+|---|---|---|
+| 900, 901, 903 | `Audd::AuthenticationError` | The api_token is missing, wrong, or inactive |
+| 902 | `Audd::QuotaError` | Quota or per-copy limit reached |
+| 904, 905 | `Audd::SubscriptionError` | The endpoint isn't available on this plan |
+| 50, 51, 600, 601, 602, 700, 701, 702, 906 | `Audd::InvalidRequestError` | Bad input — no file or url sent, malformed parameters |
+| 300, 400, 500 | `Audd::InvalidAudioError` | The audio itself couldn't be read or fingerprinted |
+| 610 | `Audd::StreamLimitError` | Subscription stream slots exhausted |
+| 611 | `Audd::RateLimitError` | Per-stream daily rate limit |
+| 907 | `Audd::NotReleasedError` | The song hasn't been released yet |
+| 19, 31337 | `Audd::BlockedError` | Security, abuse, sanctions, IP ban, or maintenance |
+| 20 | `Audd::NeedsUpdateError` | Client needs updating / paid version required |
+| 100, 1000, anything else | `Audd::ServerError` | Upstream failure, and every code this gem doesn't recognise |
+
+Code 51 is the exception to the rule: it's a soft deprecation warning. When the
+server sends it *and* still returns a result, the gem warns on stderr and hands
+you the result instead of raising.
+
+Every `Audd::ApiError` carries `error_code`, `error_message`, `http_status`,
+`request_id`, `request_params`, `request_method`, `branded_message` and
+`raw_response` — enough to log an incident or open a ticket with AudD support.
+
+```ruby
+begin
+  result = audd.recognize(file: file).execute!
+rescue Audd::AuthenticationError => e
+  abort "check your token: #{e.message}"
+rescue Audd::InvalidAudioError => e
+  warn "we sent something unusable: #{e.error_message}"
+rescue Audd::ApiError => e
+  warn "AudD ##{e.error_code}: #{e.error_message} (request_id=#{e.request_id})"
+end
+```
+
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+### Testing
+We use contract testing based on the audd openapi https://github.com/AudDMusic/audd-openapi library.
+
+It's vendored as a git submodule at `spec/audd-openapi`, pinned to a tag (`v1.4.4`)
+so the contract can't move under us without a reviewable diff. Fetch it with:
+
+```bash
+git submodule update --init
+```
+
+The contract specs read both the spec document — to check we only send the form
+fields `POST /` documents, and that every error code it enumerates maps to an
+exception class — and the captured response fixtures, which they replay through
+the real client. Without the submodule those specs skip rather than fail, so the
+rest of the suite still runs on a fresh clone.
+
+To take a new spec version: update the submodule to the new tag, bump
+`OpenAPI::PINNED_VERSION` in `spec/support/openapi.rb`, and run `rake`.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/RowanMcDonald /audd. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/[USERNAME]/audd/blob/main/CODE_OF_CONDUCT.md).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the Audd project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/audd/blob/main/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "standard/rake"
+
+task default: %i[spec standard]

data/lib/audd/client.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative "errors"
+require_relative "http_client"
+require_relative "recognize_request"
+
+module Audd
+  class Client
+    attr_reader :api_token, :base_url
+
+    def initialize(api_token:, base_url:)
+      @api_token = api_token
+      @base_url = base_url
+      @http_client = HttpClient.new
+    end
+
+    def post(path, fields:, timeout:, file: nil)
+      @http_client.post_form(
+        "#{base_url}#{path}",
+        fields: fields.merge("api_token" => api_token),
+        timeout: timeout,
+        file: file
+      )
+    end
+
+    def inspect
+      "#<#{self.class.name} base_url=#{base_url.inspect} api_token=[FILTERED]>"
+    end
+  end
+end

data/lib/audd/errors.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module Audd
+  # Base of everything this gem raises. `rescue Audd::Error` catches the lot.
+  class Error < StandardError; end
+
+  # Raised before any request is made.
+
+  # No api_token was supplied and AUDD_API_TOKEN is unset.
+  class ConfigurationError < Error; end
+
+  # The caller passed something the API can't accept: neither (or both) of
+  # `file:`/`url:`, an unknown `return` source, an unreadable file.
+  class InvalidParameterError < Error; end
+
+  # Raised when no usable response came back.
+
+  # Network, DNS, or TLS failure — nothing was received.
+  class ConnectionError < Error; end
+
+  # The request outran its timeout. Recognition holds the connection open
+  # while the server fingerprints the audio, so this is the one to watch.
+  class TimeoutError < ConnectionError; end
+
+  # A 2xx response whose body wasn't parseable JSON.
+  class SerializationError < Error
+    attr_reader :raw_body
+
+    def initialize(message, raw_body: "")
+      @raw_body = raw_body
+      super(message)
+    end
+  end
+
+  # The server answered with `status: "error"`. Carries the AudD error code
+  # plus the server's full echo of the request, which is what AudD support
+  # asks for.
+  class ApiError < Error
+    attr_reader :error_code, :error_message, :http_status, :request_id,
+      :request_params, :request_method, :branded_message, :raw_response
+
+    def initialize(error_code:, error_message:, http_status: nil, request_id: nil,
+      request_params: {}, request_method: nil, branded_message: nil, raw_response: nil)
+      @error_code = error_code
+      @error_message = error_message
+      @http_status = http_status
+      @request_id = request_id
+      @request_params = request_params || {}
+      @request_method = request_method
+      @branded_message = branded_message
+      @raw_response = raw_response
+      super("[##{error_code}] #{error_message}")
+    end
+  end
+
+  # 900 / 901 / 903 — the token is the problem.
+  class AuthenticationError < ApiError; end
+
+  # 902 — quota or per-copy limit reached.
+  class QuotaError < ApiError; end
+
+  # 904 / 905 — the endpoint isn't available on this plan.
+  class SubscriptionError < ApiError; end
+
+  # 50 / 51 / 600 / 601 / 602 / 700 / 701 / 702 / 906 — bad input from the caller.
+  class InvalidRequestError < ApiError; end
+
+  # 300 / 400 / 500 — the audio itself is the problem.
+  class InvalidAudioError < ApiError; end
+
+  # 610 — subscription stream slots exhausted.
+  class StreamLimitError < ApiError; end
+
+  # 611 — per-stream daily rate limit.
+  class RateLimitError < ApiError; end
+
+  # 907 — the song hasn't been released yet.
+  class NotReleasedError < ApiError; end
+
+  # 19 / 31337 — security, abuse, sanctions, IP ban, or maintenance.
+  class BlockedError < ApiError; end
+
+  # 20 — the client needs updating / a paid version is required.
+  class NeedsUpdateError < ApiError; end
+
+  # 100 / 1000, and every code this gem doesn't recognise.
+  class ServerError < ApiError; end
+
+  # Maps AudD's numeric error codes onto the classes above. The code list is
+  # the enum in the OpenAPI `ErrorResponse` schema; 40 has no documented
+  # meaning, so it falls through to ServerError along with anything new.
+  ERROR_CLASSES_BY_CODE = {
+    900 => AuthenticationError,
+    901 => AuthenticationError,
+    903 => AuthenticationError,
+    902 => QuotaError,
+    904 => SubscriptionError,
+    905 => SubscriptionError,
+    50 => InvalidRequestError,
+    51 => InvalidRequestError,
+    600 => InvalidRequestError,
+    601 => InvalidRequestError,
+    602 => InvalidRequestError,
+    700 => InvalidRequestError,
+    701 => InvalidRequestError,
+    702 => InvalidRequestError,
+    906 => InvalidRequestError,
+    300 => InvalidAudioError,
+    400 => InvalidAudioError,
+    500 => InvalidAudioError,
+    610 => StreamLimitError,
+    611 => RateLimitError,
+    907 => NotReleasedError,
+    19 => BlockedError,
+    31337 => BlockedError,
+    20 => NeedsUpdateError,
+    100 => ServerError,
+    1000 => ServerError
+  }.freeze
+
+  # Unknown codes are still errors — just not ones we can name.
+  def self.error_class_for(code)
+    ERROR_CLASSES_BY_CODE.fetch(code, ServerError)
+  end
+end

data/lib/audd/http_client.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "openssl"
+require "securerandom"
+require "uri"
+
+require_relative "errors"
+
+module Audd
+  class HttpClient
+    Response = Struct.new(:status, :body, :request_id, keyword_init: true)
+
+    USER_AGENT = "audd-ruby/#{VERSION} ruby/#{RUBY_VERSION} (#{RUBY_PLATFORM})"
+
+    # AudD only accepts multipart uploads; the field name for the upload is
+    # fixed by the API.
+    FILE_FIELD = "file"
+
+    # POSTs `fields` (and optionally one file) to `url`.
+    #
+    # @param file [Array(String, IO), nil] a [filename, io] pair
+    def post_form(url, fields:, timeout:, file: nil)
+      uri = URI.parse(url)
+      boundary = SecureRandom.hex(16)
+
+      request = Net::HTTP::Post.new(uri)
+      request["User-Agent"] = USER_AGENT
+      request["Content-Type"] = "multipart/form-data; boundary=#{boundary}"
+      request.body = multipart_body(fields, file, boundary)
+
+      perform(uri, request, timeout)
+    end
+
+    private
+
+    def perform(uri, request, timeout)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.open_timeout = timeout
+      http.read_timeout = timeout
+      http.write_timeout = timeout
+
+      response = http.start { |session| session.request(request) }
+      Response.new(
+        status: response.code.to_i,
+        body: response.body,
+        request_id: response["x-request-id"]
+      )
+    rescue Net::OpenTimeout, Net::ReadTimeout, Net::WriteTimeout => e
+      raise TimeoutError, "Request to #{uri} timed out after #{timeout}s (#{e.class})"
+    rescue SocketError, SystemCallError, IOError,
+      OpenSSL::SSL::SSLError, Net::HTTPBadResponse, Net::ProtocolError => e
+      raise ConnectionError, "Request to #{uri} failed: #{e.class}: #{e.message}"
+    end
+
+    def multipart_body(fields, file, boundary)
+      body = +"".b
+
+      fields.each do |name, value|
+        body << "--#{boundary}\r\n".b
+        body << "Content-Disposition: form-data; name=\"#{quote(name)}\"\r\n\r\n".b
+        body << value.to_s.b
+        body << "\r\n".b
+      end
+
+      if file
+        filename, io = file
+        body << "--#{boundary}\r\n".b
+        body << "Content-Disposition: form-data; name=\"#{FILE_FIELD}\"; " \
+                "filename=\"#{quote(filename)}\"\r\n".b
+        body << "Content-Type: application/octet-stream\r\n\r\n".b
+        body << io.read.b
+        body << "\r\n".b
+      end
+
+      body << "--#{boundary}--\r\n".b
+      body
+    end
+
+    # Quotes are structural in a Content-Disposition header and newlines would
+    # let a filename inject headers of its own.
+    def quote(value)
+      value.to_s.gsub(/["\r\n]/, "_")
+    end
+  end
+end

data/lib/audd/models/apple_music_metadata.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require_relative "model"
+
+module Audd
+  # Mirror of the upstream Apple Music track payload, passed through verbatim
+  # by AudD. Field names stay camelCase to match the JSON keys.
+  class AppleMusicMetadata < Model
+    field :previews
+    field :artwork
+    field :artist_name, "artistName"
+    field :url
+    field :disc_number, "discNumber"
+    field :genre_names, "genreNames"
+    field :duration_in_millis, "durationInMillis"
+    field :release_date, "releaseDate"
+    field :name
+    field :isrc
+    field :album_name, "albumName"
+    field :play_params, "playParams"
+    field :track_number, "trackNumber"
+    field :composer_name, "composerName"
+  end
+end

data/lib/audd/models/deezer_metadata.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative "model"
+
+module Audd
+  # Mirror of the upstream Deezer track payload. Absent for some tracks.
+  class DeezerMetadata < Model
+    field :id
+    field :readable
+    field :title
+    field :title_short
+    field :title_version
+    field :link
+    field :duration
+    field :rank
+    field :explicit_lyrics
+    field :explicit_content_lyrics
+    field :explicit_content_cover
+    field :preview
+    field :md5_image
+    field :artist
+    field :album
+    field :type
+  end
+end

data/lib/audd/models/error_response.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require_relative "model"
+
+module Audd
+  # Envelope returned with `status: "error"`. ResponseParser turns one of these
+  # into the matching Audd::ApiError subclass; it is exposed because the
+  # exception hands the parsed envelope back on #raw_response.
+  class ErrorResponse < Model
+    field :status
+    field :error
+    # The standard endpoint names this `request_params`; the enterprise
+    # endpoint names the same thing `requested_params`. Normalized in #initialize.
+    field :request_params
+    field :request_api_method
+    field :request_http_method
+    field :execution_time
+    field :result
+
+    def initialize(raw)
+      super
+      @request_params ||= raw["requested_params"]
+    end
+
+    def error_code
+      dig_error("error_code")
+    end
+
+    def error_message
+      dig_error("error_message")
+    end
+
+    # Codes 19 and 31337 may carry a "branded" artist/title instead of a real
+    # result. It is deliberately not surfaced as a recognition result.
+    def branded_message
+      return nil unless result.is_a?(Hash)
+
+      parts = [result["artist"], result["title"]].compact.map(&:to_s).reject(&:empty?)
+      parts.empty? ? nil : parts.join(" — ")
+    end
+
+    private
+
+    # `error` is documented as an object, but a bare string shows up in the
+    # wild; surface it as the message rather than blowing up on #[].
+    def dig_error(key)
+      case error
+      when Hash then error[key]
+      when String then (key == "error_message") ? error : nil
+      end
+    end
+  end
+end

data/lib/audd/models/model.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Audd
+  # Base for the response objects. Subclasses declare the fields their OpenAPI
+  # schema documents; every instance also keeps the untouched `raw` hash,
+  # because those schemas are all `additionalProperties: true` — Apple, Spotify
+  # and friends ship new keys without warning and AudD passes them through
+  # verbatim. Reach unmapped keys with `result["some_new_key"]`.
+  class Model
+    class << self
+      # Declares a reader backed by `key` in the raw payload. An optional block
+      # casts the raw value (used to nest sub-models).
+      def field(name, key = name.to_s, &cast)
+        fields[name] = [key, cast]
+        attr_reader(name)
+      end
+
+      def fields
+        @fields ||= superclass.respond_to?(:fields) ? superclass.fields.dup : {}
+      end
+
+      # Anything that isn't an object (`null`, mostly) is absence, not an error.
+      def from_json(raw)
+        new(raw) if raw.is_a?(Hash)
+      end
+    end
+
+    attr_reader :raw
+
+    def initialize(raw)
+      @raw = raw
+      self.class.fields.each do |name, (key, cast)|
+        value = raw[key]
+        value = cast.call(value) if cast && !value.nil?
+        instance_variable_set(:"@#{name}", value)
+      end
+    end
+
+    def [](key)
+      raw[key.to_s]
+    end
+
+    def to_h
+      raw
+    end
+
+    def ==(other)
+      other.instance_of?(self.class) && other.raw == raw
+    end
+    alias_method :eql?, :==
+
+    def hash
+      [self.class, raw].hash
+    end
+
+    # Only the fields that are actually present — these payloads are wide and
+    # mostly empty, and a full dump buries the useful bits.
+    def inspect
+      populated = self.class.fields.keys.filter_map do |name|
+        value = public_send(name)
+        "#{name}=#{value.inspect}" unless value.nil?
+      end
+      "#<#{self.class.name} #{populated.join(" ")}>"
+    end
+  end
+end

data/lib/audd/models/music_brainz_entry.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require_relative "model"
+
+module Audd
+  # A single MusicBrainz recording match. AudD returns an array of these,
+  # because MusicBrainz matching often surfaces several candidates.
+  class MusicBrainzEntry < Model
+    field :id
+    # MusicBrainz sometimes returns score as a string, sometimes as an integer.
+    field :score
+    field :title
+    field :length
+    field :disambiguation
+    field :video
+    field :artist_credit, "artist-credit"
+    field :releases
+    field :isrcs
+    field :tags
+  end
+end

data/lib/audd/models/recognition_result.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require "uri"
+
+require_relative "model"
+require_relative "apple_music_metadata"
+require_relative "deezer_metadata"
+require_relative "music_brainz_entry"
+require_relative "spotify_metadata"
+
+module Audd
+  # A single recognition result. Which fields are populated depends on which
+  # catalog matched:
+  #
+  # * public-DB match — +artist+, +title+, +album+, +release_date+, +label+
+  #   and +song_link+ are populated and +audio_id+ is absent;
+  # * custom-DB match (your own fingerprint catalog) — only +timecode+ and
+  #   +audio_id+ are populated.
+  #
+  # Use #public_match? / #custom_match? rather than testing +artist+ for nil.
+  class RecognitionResult < Model
+    # Only lis.tn-hosted song links serve cover art from `?thumb`.
+    THUMBNAIL_HOST = "lis.tn"
+
+    # Position in the recognized song (MM:SS) at which the matched fragment plays.
+    field :timecode
+    field :audio_id
+    field :artist
+    field :title
+    field :album
+    field :release_date
+    field :label
+    field :song_link
+    field(:apple_music) { |v| AppleMusicMetadata.from_json(v) }
+    field(:spotify) { |v| SpotifyMetadata.from_json(v) }
+    field(:deezer) { |v| DeezerMetadata.from_json(v) }
+    field(:musicbrainz) { |v| Array(v).filter_map { |e| MusicBrainzEntry.from_json(e) } }
+
+    # Matched against your own fingerprint catalog rather than the public DB.
+    def custom_match?
+      !audio_id.nil?
+    end
+
+    def public_match?
+      audio_id.nil?
+    end
+
+    # Cover art for the match, or nil when there's no song_link to build it
+    # from — appending ?thumb only means anything on lis.tn.
+    def thumbnail_url
+      return nil if song_link.nil?
+      return nil unless URI.parse(song_link).host == THUMBNAIL_HOST
+
+      "#{song_link}?thumb"
+    rescue URI::InvalidURIError
+      nil
+    end
+  end
+end

data/lib/audd/models/recognize_success_response.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require_relative "model"
+require_relative "recognition_result"
+
+module Audd
+  # Envelope returned by POST api.audd.io/ on success. `result` is nil when the
+  # audio was processed fine but nothing matched — that is a successful
+  # response, not an error.
+  class RecognizeSuccessResponse < Model
+    field :status
+    field(:result) { |v| RecognitionResult.from_json(v) }
+
+    def match?
+      !result.nil?
+    end
+  end
+end

data/lib/audd/models/spotify_metadata.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative "model"
+
+module Audd
+  # Mirror of the upstream Spotify track payload.
+  class SpotifyMetadata < Model
+    field :album
+    field :artists
+    field :available_markets
+    field :disc_number
+    field :duration_ms
+    field :explicit
+    field :external_ids
+    field :external_urls
+    field :href
+    field :id
+    field :is_local
+    field :is_playable
+    field :linked_from
+    field :name
+    field :popularity
+    field :track_number
+    field :type
+    field :uri
+  end
+end

data/lib/audd/recognize_request.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require_relative "errors"
+require_relative "models/recognize_success_response"
+require_relative "response_parser"
+require_relative "source"
+
+module Audd
+  # Chainable builder for POST api.audd.io/. Built by Audd::Client#recognize;
+  # nothing is sent until #execute!.
+  #
+  #   audd.recognize(file: "clip.mp3")
+  #       .return_metadata(:apple_music, :spotify)
+  #       .market("us")
+  #       .execute!
+  class RecognizeRequest
+    RETURN_METADATA_SOURCES = %w[apple_music spotify deezer musicbrainz].freeze
+
+    # The server holds the connection open while it fingerprints the audio,
+    # so this is generous by HTTP standards.
+    DEFAULT_TIMEOUT = 60
+
+    attr_reader :file, :url
+
+    def initialize(client:, file: nil, url: nil, timeout: DEFAULT_TIMEOUT)
+      if file.nil? == url.nil?
+        raise InvalidParameterError,
+          "recognize requires exactly one of file: or url:, got " \
+          "#{file.nil? ? "neither" : "both"}."
+      end
+
+      @client = client
+      @file = file
+      @url = url
+      @timeout = timeout
+      @return_metadata = []
+      @market = nil
+    end
+
+    # Extra metadata to fetch for the match, e.g. :apple_music, :spotify.
+    # Repeated calls accumulate.
+    def return_metadata(*sources)
+      sources = sources.flatten.map(&:to_s)
+      unknown = sources - RETURN_METADATA_SOURCES
+
+      unless unknown.empty?
+        raise InvalidParameterError,
+          "unknown return_metadata source(s): #{unknown.join(", ")}. " \
+          "Valid sources: #{RETURN_METADATA_SOURCES.join(", ")}."
+      end
+
+      @return_metadata |= sources
+      self
+    end
+
+    # ISO country code for the regional Apple Music / Spotify catalogs.
+    def market(code)
+      @market = code.to_s
+      self
+    end
+
+    # Overrides DEFAULT_TIMEOUT for this request, in seconds.
+    def timeout(seconds)
+      @timeout = seconds
+      self
+    end
+
+    # Sends the request.
+    #
+    # @return [Audd::RecognitionResult, nil] nil when the audio was processed
+    #   but nothing matched — a successful response, not an error.
+    def execute!
+      body = Source.with_file(@file) do |file_part|
+        response = @client.post("/", fields: form_fields, timeout: @timeout, file: file_part)
+        ResponseParser.decode!(response)
+      end
+
+      RecognizeSuccessResponse.new(body).result
+    end
+
+    # The multipart fields this request will send, minus the api_token the
+    # client adds.
+    def form_fields
+      fields = {}
+      fields["url"] = @url if @url
+      fields["return"] = @return_metadata.join(",") unless @return_metadata.empty?
+      fields["market"] = @market if @market
+      fields
+    end
+  end
+end

data/lib/audd/response_parser.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require "json"
+
+require_relative "errors"
+require_relative "models/error_response"
+
+module Audd
+  # Turns a raw HTTP response into a decoded success body, or raises the
+  # matching Audd::Error subclass.
+  module ResponseParser
+    HTTP_CLIENT_ERROR_FLOOR = 400
+
+    # Code 51 is a soft deprecation: the server fulfilled the request but is
+    # warning about a parameter. When a result came back with it, warn and
+    # carry on rather than raising.
+    DEPRECATED_PARAMS_CODE = 51
+
+    class << self
+      # @return [Hash] the parsed `status: "success"` body
+      def decode!(response)
+        body = parse_json(response)
+        return handle_deprecation(body) if deprecation_pass_through?(body)
+
+        case body["status"]
+        when "success" then body
+        when "error" then raise_api_error(body, response)
+        else
+          raise ServerError.new(
+            error_code: 0,
+            error_message: "Unexpected response status: #{body["status"].inspect}",
+            http_status: response.status,
+            request_id: response.request_id,
+            raw_response: body
+          )
+        end
+      end
+
+      private
+
+      def parse_json(response)
+        body = begin
+          JSON.parse(response.body.to_s)
+        rescue JSON::ParserError
+          nil
+        end
+        return body if body.is_a?(Hash)
+
+        # A non-JSON body on a failing status is the proxy or gateway talking,
+        # not AudD — report it as a server error and keep the status code.
+        if response.status >= HTTP_CLIENT_ERROR_FLOOR
+          raise ServerError.new(
+            error_code: 0,
+            error_message: "HTTP #{response.status} with non-JSON response body",
+            http_status: response.status,
+            request_id: response.request_id,
+            raw_response: response.body
+          )
+        end
+
+        raise SerializationError.new(
+          "Could not parse the AudD response as JSON",
+          raw_body: response.body.to_s
+        )
+      end
+
+      def deprecation_pass_through?(body)
+        error = body["error"]
+        error.is_a?(Hash) &&
+          error["error_code"] == DEPRECATED_PARAMS_CODE &&
+          !body["result"].nil?
+      end
+
+      def handle_deprecation(body)
+        warn("[audd] #{body.dig("error", "error_message")}")
+        body.except("error").merge("status" => "success")
+      end
+
+      def raise_api_error(body, response)
+        envelope = ErrorResponse.new(body)
+        code = Integer(envelope.error_code, exception: false) || 0
+
+        raise Audd.error_class_for(code).new(
+          error_code: code,
+          error_message: envelope.error_message.to_s,
+          http_status: response.status,
+          request_id: response.request_id,
+          request_params: envelope.request_params,
+          request_method: envelope.request_api_method,
+          branded_message: envelope.branded_message,
+          raw_response: envelope
+        )
+      end
+    end
+  end
+end

data/lib/audd/source.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+require_relative "errors"
+
+module Audd
+  # Normalizes whatever the caller passed as `file:` into the [filename, io]
+  # pair HttpClient wants.
+  module Source
+    FALLBACK_FILENAME = "upload.bin"
+
+    # Yields [filename, io], closing only handles we opened ourselves — a
+    # caller-supplied IO stays the caller's to manage.
+    def self.with_file(file)
+      return yield(nil) if file.nil?
+
+      if file.respond_to?(:read)
+        name = file.respond_to?(:path) ? File.basename(file.path) : FALLBACK_FILENAME
+        yield [name, file]
+      else
+        path = Pathname.new(file.to_s)
+        unless path.file?
+          raise InvalidParameterError,
+            "file: #{file.inspect} is not a readable file. Pass a path, a " \
+            "Pathname, or an open IO — or use url: to have AudD fetch it."
+        end
+        path.open("rb") { |io| yield [path.basename.to_s, io] }
+      end
+    end
+  end
+end

data/lib/audd/version.rb

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

data/lib/audd.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require_relative "audd/version"
+require_relative "audd/errors"
+
+require_relative "audd/models/model"
+require_relative "audd/models/apple_music_metadata"
+require_relative "audd/models/deezer_metadata"
+require_relative "audd/models/music_brainz_entry"
+require_relative "audd/models/spotify_metadata"
+require_relative "audd/models/recognition_result"
+require_relative "audd/models/recognize_success_response"
+require_relative "audd/models/error_response"
+
+require_relative "audd/http_client"
+require_relative "audd/response_parser"
+require_relative "audd/source"
+require_relative "audd/recognize_request"
+require_relative "audd/client"
+
+# Unofficial Ruby SDK for the AudD music recognition API.
+#
+#   audd = Audd.new("your_token")
+#   result = audd.recognize(file: "clip.mp3").execute!
+#   result&.title
+#
+# See https://docs.audd.io/ for the API itself.
+module Audd
+  class API
+    API_BASE = "https://api.audd.io"
+    ENTERPRISE_BASE = "https://enterprise.audd.io"
+
+    def initialize(api_token)
+      @api_token = api_token
+    end
+
+    def recognize(file: nil, url: nil)
+      client = Client.new(api_token:, base_url: API_BASE)
+
+      RecognizeRequest.new(client: client, file: file, url: url)
+    end
+
+    def recognize_enterprise(file: nil, url: nil)
+      raise NotImplementedError
+    end
+
+    def find_lyrics(query)
+      raise NotImplementedError
+    end
+
+    def inspect
+      "#<#{self.class.name} api_token=[FILTERED]>"
+    end
+
+    private
+
+    attr_reader :api_token
+  end
+
+  def self.new(api_token)
+    if api_token.nil?
+      raise ConfigurationError, "No AudD api_token given. Get one at https://dashboard.audd.io."
+    end
+
+    API.new(api_token)
+  end
+end

data/sig/audd.rbs

@@ -0,0 +1,4 @@
+module Audd
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,67 @@
+--- !ruby/object:Gem::Specification
+name: audd
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- Rowan McDonald
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: SDK for AudD music recognition software.
+email:
+- rowjaim@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".standard.yml"
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/audd.rb
+- lib/audd/client.rb
+- lib/audd/errors.rb
+- lib/audd/http_client.rb
+- lib/audd/models/apple_music_metadata.rb
+- lib/audd/models/deezer_metadata.rb
+- lib/audd/models/error_response.rb
+- lib/audd/models/model.rb
+- lib/audd/models/music_brainz_entry.rb
+- lib/audd/models/recognition_result.rb
+- lib/audd/models/recognize_success_response.rb
+- lib/audd/models/spotify_metadata.rb
+- lib/audd/recognize_request.rb
+- lib/audd/response_parser.rb
+- lib/audd/source.rb
+- lib/audd/version.rb
+- sig/audd.rbs
+homepage: https://github.com/RowanMcDonald/audd
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/RowanMcDonald/audd
+  source_code_uri: https://github.com/RowanMcDonald/audd
+  changelog_uri: https://github.com/RowanMcDonald/audd/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: SDK for AudD music recognition software.
+test_files: []