phonetics 4.0.0-arm64-darwin

data/lib/phonetics/transcriptions.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+require 'open-uri'
+require 'json'
+
+module Phonetics
+  def self.transcription_for(phrase)
+    phrase.downcase.split(' ').map { |word| Transcriptions[word] }.join
+  end
+
+  module Transcriptions
+    extend self
+
+    TranscriptionFile = File.join(__dir__, '..', 'common_ipa_transcriptions.json')
+    TranscriptionsURL = 'https://jackdanger.com/common_ipa_transcriptions.json'
+
+    SourcesByPreference = [/wiktionary/, /cmu/, /phonemicchart.com/].freeze
+
+    def [](key)
+      entry = transcriptions[key]
+      return unless entry
+      return unless entry['ipa']
+
+      SourcesByPreference.each do |preferred_source|
+        entry['ipa'].each_key do |source|
+          return entry['ipa'][source] if source =~ preferred_source
+        end
+      end
+      nil
+    end
+
+    def words
+      transcriptions.keys
+    end
+
+    def transcriptions
+      @transcriptions ||= begin
+        download! unless File.exist?(TranscriptionFile)
+        load_from_disk!
+      end
+    end
+
+    # Lazily loaded from JSON file on disk
+    def load_from_disk!
+      @transcriptions = JSON.parse(File.read(TranscriptionFile))
+    end
+
+    # rubocop:disable Security/Open
+    def download!
+      File.open(Transcriptions, 'w') { |f| f.write(URI.open(TranscriptionsURL).read) }
+    end
+    # rubocop:enable Security/Open
+
+    # rubocop:disable Metrics/CyclomaticComplexity
+    def trie(max_rarity = nil)
+      # Let's turn this:
+      #
+      #    "century": {
+      #      "rarity": 462.0,
+      #      "ipa": {
+      #        "cmu": "sɛntʃɝɪ",
+      #        "phonemicchart.com": "sentʃərɪ",
+      #        "wiktionary": "sɛntʃəɹi",
+      #        "wiktionary2": "sɛntʃɹi",
+      #        "wiktionary3": "sɛntʃʊɹi"
+      #      },
+      #      "alt_display": "CENTURY"
+      #    }
+      #
+      # into this:
+      #
+      #   "s": {
+      #     "e": {
+      #       "n": {
+      #         "t": {
+      #           "ʃ": {
+      #             "ʊ": {
+      #               "ɹ": {
+      #                 "i": {
+      #                   "terminal": [Term('century')],
+      #                 },
+      #               },
+      #             },
+      #             "ə": {
+      #               "r": {
+      #                 "ɪ": {
+      #                   "terminal": [Term('century')],
+      #                 },
+      #               },
+      #             },
+      #             "ɹ": {
+      #               "i": {
+      #                 "terminal": [Term('century')],
+      #               },
+      #             },
+      #             "ɝ": {
+      #               "ɪ": {
+      #                 "terminal": [Term('century')],
+      #               },
+      #             },
+      #           },
+      #         },
+      #       },
+      #     },
+      #     "ɛ": {
+      #       "n": {
+      #         "t": {
+      #           "ʃ": {
+      #             "ɝ": {
+      #               "ɪ": {
+      #                 "terminal": [Term('century')],
+      #               },
+      #             },
+      #           },
+      #         },
+      #       },
+      #     },
+      #   },
+      #
+      @tries ||= {}
+      @tries[max_rarity] ||= begin
+        base_trie = {}
+        transcriptions.each do |key, entry|
+          next if max_rarity && (entry['rarity'].nil? || entry['rarity'] > max_rarity)
+
+          entry_data = {
+            word: key,
+            rarity: entry['rarity'],
+          }
+          entry.fetch('ipa', []).each_value do |transcription|
+            base_trie = construct_trie(base_trie, transcription, entry_data)
+          end
+        end
+        base_trie.freeze
+      end
+    end
+    # rubocop:enable Metrics/CyclomaticComplexity
+
+    def walk(ipa)
+      ipa.each_char.reduce(trie) { |acc, char| acc[char] }
+    end
+
+    def transcription_for(phrase)
+      phrase.downcase.split(' ').map { |word| self[word] }.join
+    end
+
+    private
+
+    # Given an portion of an existing trie (to be modified), the remainder of a
+    # char string, and an entry, walk or construct the appropriate trie nodes
+    # necessary to place the entry in a leaf.
+    def construct_trie(subtrie, chars_remaining, entry_data, depth = 0)
+      subtrie[:depth] ||= depth
+      if chars_remaining.empty?
+        # Base condition met
+        subtrie[:terminal] ||= []
+        subtrie[:terminal] << entry_data unless subtrie[:terminal].include?(entry_data)
+      else
+        next_char = chars_remaining[0]
+        subtrie[next_char] ||= {}
+        subtrie[next_char][:path] ||= subtrie[:path].to_s + next_char
+        subtrie[next_char] = construct_trie(subtrie[next_char], chars_remaining[1..], entry_data, depth + 1)
+      end
+      subtrie
+    end
+  end
+end

data/lib/phonetics/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Phonetics
+  VERSION = File.read(File.join(File.dirname(__FILE__), '../../VERSION')).chomp
+end

data/lib/phonetics.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+# Phonetics — IPA-based phonetic distance.
+#
+# The entire algorithmic core is written in Rust (see <repo>/rust/
+# phonetics) and loaded as a native extension via Magnus. This file
+# layers ergonomic Ruby idioms on top of the bare module functions
+# that the extension exports.
+#
+# Two-tier distance API:
+#
+#   Phonetics.distance(p1, p2)              acoustic per-phoneme, 0..1
+#   Phonetics.levenshtein(s1, s2)           strict edit distance
+#   Phonetics.confusion(s1, s2)             listener-confusion distance
+#   Phonetics.similarity(s1, s2)            normalised 0..1
+#   Phonetics.sub_cost(p1, p2)              perceptual per-phoneme
+#   Phonetics.tokenize(ipa, boundaries:)    phoneme stream
+require 'delegate'
+
+require_relative 'phonetics/phonetics_ruby'
+require_relative 'phonetics/transcriptions'
+
+module Phonetics
+  # The native binding exposes the tokenizer as `_tokenize(input,
+  # boundaries)`. Magnus's `function!` macro doesn't bridge Ruby
+  # keyword arguments through to Rust, so we wrap it in a Ruby method
+  # that does accept the kwarg.
+  def self.tokenize(input, boundaries: false)
+    _tokenize(input, boundaries)
+  end
+
+  # ------------------------------------------------------------------
+  # Phonetics::String — iterator over phonemes in an IPA string.
+  # ------------------------------------------------------------------
+  class String < SimpleDelegator
+    def each_phoneme(boundaries: false)
+      Phonetics.tokenize(to_s, boundaries: boundaries).each
+    end
+  end
+
+  # ------------------------------------------------------------------
+  # Backwards-compatible namespaced API.
+  #
+  # The previous Ruby+C implementation exposed these under sub-modules.
+  # Keep them as thin delegators so existing callers don't break —
+  # there's nothing interesting happening here, just forwarding.
+  # ------------------------------------------------------------------
+
+  module Levenshtein
+    INDEL_COST     = 1.0
+    TRANSPOSE_COST = 0.8
+
+    def self.distance(s1, s2, _verbose = false)
+      return if s1.nil? || s2.nil?
+
+      Phonetics.levenshtein(s1, s2)
+    end
+  end
+
+  module Confusion
+    GAP_OPEN             = 0.60
+    GAP_EXTEND           = 0.25
+    WEAK_INDEL_COST      = 0.15
+    BOUNDARY_INDEL_COST  = 0.02
+
+    def self.distance(s1, s2, verbose: false)
+      _ = verbose
+      Phonetics.confusion(s1, s2)
+    end
+
+    def self.similarity(s1, s2)
+      Phonetics.similarity(s1, s2)
+    end
+
+    def self.sub_cost(a, b)
+      Phonetics.sub_cost(a, b)
+    end
+  end
+end

data/phonetics.gemspec

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require_relative 'lib/phonetics/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'phonetics'
+  spec.version       = Phonetics::VERSION
+  spec.authors       = ['Jack Danger']
+  spec.email         = ['github@jackcanty.com']
+
+  spec.summary       = 'IPA-based phonetic distance: strict edit distance, listener-confusion distance, and per-phoneme acoustic and perceptual scoring.'
+  spec.description   = <<~DESC
+    Tools for working with the International Phonetic Alphabet. Two-tier
+    distance API — strict acoustic and listener-perception — backed by a
+    Rust core compiled in via Magnus. Calibrated against Mad Gab puzzle
+    data and English speech-perception literature.
+  DESC
+  spec.homepage      = 'https://github.com/JackDanger/phonetics'
+  spec.license       = 'MIT'
+
+  spec.required_ruby_version = '>= 3.0'
+  spec.required_rubygems_version = '>= 3.3.11'
+
+  spec.metadata['homepage_uri']    = spec.homepage
+  spec.metadata['source_code_uri'] = spec.homepage
+
+  spec.extensions = ['ext/phonetics_ruby/extconf.rb']
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    tracked = `git ls-files -z`.split("\x0").reject do |f|
+      f.match(%r{\A(test|spec|features)/}) ||
+        f.match(%r{\Aext/phonetics_ruby/(target|Cargo.lock|Makefile)})
+    end
+    # The vendored Rust core isn't tracked in git (it's a build
+    # artifact populated by `rake vendor_rust`), but it IS shipped
+    # in the .gem tarball so end users don't need the source
+    # workspace to compile the extension.
+    vendor = Dir.glob('ext/phonetics_ruby/vendor/**/*', File::FNM_DOTMATCH).reject do |p|
+      File.directory?(p) ||
+        p.include?('/target/') ||
+        p.end_with?('Cargo.lock', '/.', '/..')
+    end
+    (tracked + vendor).uniq.sort
+  end
+
+  spec.require_paths = ['lib']
+
+  spec.add_dependency 'rb_sys', '~> 0.9'
+
+  spec.add_development_dependency 'bundler'
+  spec.add_development_dependency 'rake'
+  spec.add_development_dependency 'rake-compiler'
+  spec.add_development_dependency 'rspec'
+  spec.add_development_dependency 'rubocop'
+end

metadata

@@ -0,0 +1,149 @@
+--- !ruby/object:Gem::Specification
+name: phonetics
+version: !ruby/object:Gem::Version
+  version: 4.0.0
+platform: arm64-darwin
+authors:
+- Jack Danger
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-05-12 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake-compiler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: |
+  Tools for working with the International Phonetic Alphabet. Two-tier
+  distance API — strict acoustic and listener-perception — backed by a
+  Rust core compiled in via Magnus. Calibrated against Mad Gab puzzle
+  data and English speech-perception literature.
+email:
+- github@jackcanty.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".rubocop.yml"
+- CHANGELOG
+- CODE_OF_CONDUCT.md
+- Dockerfile
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- VERSION
+- _site/orthographic_levenshtein_example.png
+- _site/phonetic_levenshtein_example.png
+- _site/vowel_chart_b_words.jpg
+- bin/console
+- bin/gempush-if-changed
+- bin/phonetics
+- ext/phonetics_ruby/vendor/phonetics/README.md
+- lib/common_ipa_transcriptions.json
+- lib/phonetics.rb
+- lib/phonetics/3.2/phonetics_ruby.bundle
+- lib/phonetics/3.3/phonetics_ruby.bundle
+- lib/phonetics/3.4/phonetics_ruby.bundle
+- lib/phonetics/transcriptions.rb
+- lib/phonetics/version.rb
+- phonetics.gemspec
+homepage: https://github.com/JackDanger/phonetics
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/JackDanger/phonetics
+  source_code_uri: https://github.com/JackDanger/phonetics
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+  - - "<"
+    - !ruby/object:Gem::Version
+      version: 3.5.dev
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.3.11
+requirements: []
+rubygems_version: 3.5.23
+signing_key: 
+specification_version: 4
+summary: 'IPA-based phonetic distance: strict edit distance, listener-confusion distance,
+  and per-phoneme acoustic and perceptual scoring.'
+test_files: []