chore: import upstream snapshot with attribution

ruby/README.md

@@ -0,0 +1,138 @@
+# Vosk Ruby
+
+Ruby bindings for [Vosk](https://alphacephei.com/vosk/) — an offline speech recognition toolkit supporting 20+ languages.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "vosk"
+```
+
+Or install directly:
+
+```bash
+gem install vosk
+```
+
+The gem ships with a precompiled `libvosk` for supported platforms. On other platforms it will attempt to load a system-installed `libvosk`.
+
+## Usage
+
+### Basic transcription
+
+```ruby
+require "vosk"
+require "wavefile"
+
+# Load a model by language (downloaded automatically if not cached)
+model = Vosk::Model.new(lang: "en-us")
+
+# Or by name, or by local path:
+# model = Vosk::Model.new(model_name: "vosk-model-small-en-us-0.4")
+# model = Vosk::Model.new(model_path: "/path/to/model")
+
+WaveFile::Reader.new("audio.wav") do |reader|
+  rec = Vosk::KaldiRecognizer.new(model, reader.format.sample_rate)
+
+  reader.each_buffer(4000) do |buffer|
+    data = buffer.samples.pack(WaveFile::PACK_CODES.dig(:pcm, 16))
+    if rec.accept_waveform(data).nonzero?
+      puts rec.result        # JSON: {"text": "..."}
+    else
+      puts rec.partial_result  # JSON: {"partial": "..."}
+    end
+  end
+  puts rec.final_result
+end
+```
+
+Audio must be mono, 16-bit PCM WAV. Use [wavefile](https://github.com/jstrait/wavefile) to read it.
+
+### Grammar / keyword recognition
+
+Pass a JSON array of phrases as the third argument:
+
+```ruby
+rec = Vosk::KaldiRecognizer.new(model, sample_rate, '["one two three", "[unk]"]')
+```
+
+### Recognizer options
+
+```ruby
+rec.words = true          # include per-word timing in results
+rec.partial_words = true  # include per-word timing in partial results
+rec.max_alternatives = 5  # return n-best list instead of single result
+rec.nlsml = true          # return NLSML instead of JSON
+```
+
+### SRT subtitle generation
+
+`srt_result` reads raw PCM from any IO stream and returns an SRT-formatted string. Use ffmpeg to decode any audio format on the fly:
+
+```ruby
+require "vosk"
+
+SAMPLE_RATE = 16_000
+
+model = Vosk::Model.new(lang: "en-us")
+rec = Vosk::KaldiRecognizer.new(model, SAMPLE_RATE)
+rec.words = true # required for word-level timestamps
+
+IO.popen(["ffmpeg", "-loglevel", "quiet", "-i", "audio.mp4",
+          "-ar", SAMPLE_RATE.to_s, "-ac", "1", "-f", "s16le", "-",]) do |stream|
+  puts rec.srt_result(stream)
+end
+```
+
+The `words_per_line:` keyword controls how many words appear per subtitle line (default: 7):
+
+```ruby
+rec.srt_result(stream, words_per_line: 5)
+```
+
+### Speaker identification
+
+```ruby
+spk_model = Vosk::SpkModel.new("/path/to/spk-model")
+rec = Vosk::KaldiRecognizer.new(model, sample_rate)
+rec.spk_model = spk_model
+```
+
+### Listing available models
+
+```ruby
+puts Vosk.models      # all model names
+puts Vosk.languages   # all supported language codes
+```
+
+### Logging
+
+```ruby
+Vosk.log_level = -1   # suppress all output
+Vosk.log_level = 0    # default
+```
+
+### Transcriber CLI
+
+The gem includes a `vosk-transcriber` executable:
+
+```bash
+vosk-transcriber audio.wav
+```
+
+## Model storage
+
+Models are cached in `~/.cache/vosk/` by default, or in the directory set by `$VOSK_MODEL_PATH`.
+
+## Development
+
+```bash
+bundle install
+bundle exec rake spec
+```
+
+## License
+
+Apache-2.0