mac-say 0.1.0

data/lib/mac/say.rb

@@ -0,0 +1,277 @@
+# frozen_string_literal: true
+require_relative 'say/version'
+require 'English'
+
+# Wrapper namespace module for a Say class
+module Mac
+  # A class wrapper around the MacOS `say` commad
+  # Allows to use simple TTS on Mac right from Ruby scripts
+  class Say
+    # A regex pattern to parse say voices list output
+    VOICES_PATTERN = /(^[\w-]+)\s+([\w-]+)\s+#\s([\p{Graph}\p{Zs}]+$)/i
+
+    # An error raised when `say` command couldn't be found
+    class CommandNotFound < StandardError; end
+
+    # An error raised when a text file couldn't be found
+    class FileNotFound < StandardError; end
+
+    # An error raised when the given voice isn't valid
+    class VoiceNotFound < StandardError; end
+
+    # An error raised when there is no a feature of voice to match
+    class UnknownVoiceFeature < StandardError; end
+
+    # Current voices list
+    #
+    # @return [Array<Hash>] an array of voices Hashes supported by the say command
+    # @example Get all the voices
+    #   Mac::Say.voices #=>
+    #      [
+    #          {
+    #              :name => :agnes,
+    #              :iso_code => {
+    #                  :language => :en,
+    #                  :country => :us
+    #              },
+    #              :sample => "Isn't it nice to have a computer that will talk to you?"
+    #          },
+    #          {
+    #              :name => :albert,
+    #              :iso_code => {
+    #                  :language => :en,
+    #                  :country => :us
+    #              },
+    #              :sample => " I have a frog in my throat. No, I mean a real frog!"
+    #          },
+    #          ...
+    #      ]
+    attr_reader :voices
+
+    # Current config
+    # @return [Hash] a Hash with current configuration
+    attr_reader :config
+
+    # Say constructor: sets initial configuration for say command to use
+    #
+    # @param say_path [String] the full path to the say app binary (default: '/usr/bin/say' or USE_FAKE_SAY environment variable)
+    # @param voice [Symbol] voice to be used by the say command (default: :alex)
+    # @param rate [Integer] speech rate in words per minute (default: 175) accepts values in (175..720)
+    # @param file [String] path to the file to read (default: nil)
+    #
+    # @raise [VoiceNotFound] if the given voice doesn't exist or wasn't installed
+    def initialize(voice: :alex, rate: 175, file: nil, say_path: ENV['USE_FAKE_SAY'] || '/usr/bin/say')
+      @config = {
+        say_path: say_path,
+        voice: voice,
+        rate: rate,
+        file: file
+      }
+
+      @voices = nil
+      load_voices
+
+      raise VoiceNotFound, "Voice '#{voice}' isn't a valid voice" unless valid_voice? voice
+    end
+
+    # Read the given string with the given voice
+    #
+    # @param string [String] a text to read using say command
+    # @param voice [Symbol] voice to be used by the say command (default: :alex)
+    #
+    # @return [Array<String, Integer>] an array with the actual say command used
+    #  and it's exit code. E.g.: ["/usr/bin/say -v 'alex' -r 175", 0]
+    #
+    # @raise [CommandNotFound] if the say command wasn't found
+    # @raise [VoiceNotFound] if the given voice doesn't exist or wasn't installed
+    def self.say(string, voice = :alex)
+      mac = new(voice: voice.downcase.to_sym)
+      mac.say(string: string)
+    end
+
+    # Read the given string/file with the given voice and rate
+    #
+    # Providing file, voice or rate arguments changes instance state and influence
+    # all the subsequent #say calls unless they have their own custom arguments
+    #
+    # @param string [String] a text to read using say command
+    # @param file [String] path to the file to read (default: nil)
+    # @param voice [Symbol] voice to be used by the say command (default: :alex)
+    # @param rate [Integer] speech rate in words per minute (default: 175) accepts values in (175..720)
+    #
+    # @return [Array<String, Integer>] an array with the actual say command used
+    #  and it's exit code. E.g.: ["/usr/bin/say -v 'alex' -r 175", 0]
+    #
+    # @raise [CommandNotFound] if the say command wasn't found
+    # @raise [VoiceNotFound] if the given voice doesn't exist or wasn't installed
+    # @raise [FileNotFound] if the given file wasn't found or isn't readable by the current user
+    #
+    # @example Say something (for more examples check README.md or examples/examples.rb files)
+    #   Mac::Say.new.say string: 'Hello world' #=> ["/usr/bin/say -v 'alex' -r 175", 0]
+    #   Mac::Say.new.say string: 'Hello world', voice: :fiona #=> ["/usr/bin/say -v 'fiona' -r 175", 0]
+    #   Mac::Say.new.say file: /tmp/text.txt, rate: 300 #=> ["/usr/bin/say -f /tmp/text.txt -v 'alex' -r 300", 0]
+    def say(string: nil, file: nil, voice: nil, rate: nil)
+      if voice
+        raise VoiceNotFound, "Voice '#{voice}' isn't a valid voice" unless valid_voice?(voice)
+        @config[:voice] = voice
+      end
+
+      if file
+        raise FileNotFound, "File '#{file}' wasn't found or it's not readable by the current user" unless valid_file_path?(file)
+        @config[:file] = file
+      end
+
+      @config[:rate] = rate if rate
+
+      execute_command(string)
+    end
+
+    # Find a voice by one of its features (e.g. :name, :language, :country)
+    #
+    # @return [Array<Hash>, Hash] an array with all the voices matched by the feature or
+    #   a voice Hash if only one voice corresponds to the feature
+    #
+    # @raise [UnknownVoiceFeature] if the voice feature isn't supported
+    def self.voice(feature, name)
+      mac = new
+      mac.voice(feature, name)
+    end
+
+    # Find a voice by one of its features (e.g. :name, :language, :country)
+    #
+    # @return [Array<Hash>, Hash] an array with all the voices matched by the feature or
+    #   a voice Hash if only one voice corresponds to the feature
+    #
+    # @raise [UnknownVoiceFeature] if the voice feature isn't supported
+    def voice(feature, value)
+      raise UnknownVoiceFeature, "Voice has no '#{feature}' feature" unless [:name, :language, :country].include?(feature)
+
+      condition = feature == :name ? ->(v) { v[feature] == value } : ->(v) { v[:iso_code][feature] == value }
+      found_voices = @voices.find_all(&condition)
+
+      return if found_voices.empty?
+
+      found_voices.count == 1 ? found_voices.first : found_voices
+    end
+
+    # Get all the voices supported by the say command on current machine
+    #
+    # @return [Array<Hash>] an array of voices Hashes supported by the say command
+    # @example Get all the voices
+    #   Mac::Say.voices #=>
+    #      [
+    #          {
+    #              :name => :agnes,
+    #              :iso_code => {
+    #                  :language => :en,
+    #                  :country => :us
+    #              },
+    #              :sample => "Isn't it nice to have a computer that will talk to you?"
+    #          },
+    #          {
+    #              :name => :albert,
+    #              :iso_code => {
+    #                  :language => :en,
+    #                  :country => :us
+    #              },
+    #              :sample => " I have a frog in my throat. No, I mean a real frog!"
+    #          },
+    #          ...
+    #      ]
+    def self.voices
+      mac = new
+      mac.voices
+    end
+
+    alias read say
+
+    private
+
+    # Actual command execution using current config and the string given
+    #
+    # @param string [String] a text to read using say command
+    #
+    # @return [Array<String, Integer>] an array with the actual say command used
+    #  and it's exit code. E.g.: ["/usr/bin/say -v 'alex' -r 175", 0]
+    #
+    # @raise [CommandNotFound] if the say command wasn't found
+    # @raise [FileNotFound] if the given file wasn't found or isn't readable by the current user
+    def execute_command(string = nil)
+      say_command = generate_command
+      say = IO.popen(say_command, 'w+')
+      say.write(string) if string
+      say.close
+
+      [say_command, $CHILD_STATUS.exitstatus]
+    end
+
+    # Command generation using current config
+    #
+    # @return [String] a command to be executed with all the arguments
+    #
+    # @raise [CommandNotFound] if the say command wasn't found
+    # @raise [FileNotFound] if the given file wasn't found or isn't readable by the current user
+    def generate_command
+      say_path = @config[:say_path]
+      file = @config[:file]
+
+      raise CommandNotFound, "Command `say` couldn't be found by '#{@config[:say_path]}' path" unless valid_command_path? say_path
+
+      if file && !valid_file_path?(file)
+        raise FileNotFound, "File '#{file}' wasn't found or it's not readable by the current user"
+      end
+
+      file = file ? " -f #{@config[:file]}" : ''
+      "#{@config[:say_path]}#{file} -v '#{@config[:voice]}' -r #{@config[:rate].to_i}"
+    end
+
+    # Parsing voices list from the `say` command itself
+    # Memoize voices list for the instance
+    #
+    # @return [Array<Hash>, nil] an array of voices Hashes supported by the say command or nil
+    #   if voices where parsed before and stored in @voices instance variable
+    #
+    # @raise [CommandNotFound] if the say command wasn't found
+    def load_voices
+      return if @voices
+      say_path = @config[:say_path]
+      raise CommandNotFound, "Command `say` couldn't be found by '#{say_path}' path" unless valid_command_path? say_path
+
+      @voices = `#{say_path} -v '?'`.scan(VOICES_PATTERN).map do |voice|
+        lang = voice[1].split(/[_-]/)
+        {
+          name: voice[0].downcase.to_sym,
+          iso_code: { language: lang[0].downcase.to_sym, country: lang[1].downcase.to_sym },
+          sample: voice[2]
+        }
+      end
+    end
+
+    # Checks voice existence by the name
+    # Loads voices if they weren't loaded before
+    #
+    # @return [Boolean] if the voices name in the list of voices
+    #
+    # @raise [CommandNotFound] if the say command wasn't found
+    def valid_voice?(name)
+      load_voices unless @voices
+      voice(:name, name)
+    end
+
+    # Checks say command existence by the path
+    #
+    # @return [Boolean] if the command exists and if it is executable
+    def valid_command_path?(path)
+      File.exist?(path) && File.executable?(path)
+    end
+
+    # Checks text file existence by the path
+    #
+    # @return [Boolean] if the file exists and if it is readable
+    def valid_file_path?(path)
+      path && File.exist?(path) && File.readable?(path)
+    end
+  end
+end
+
+p Mac::Say.voice(:name, 'fuck')

data/lib/mac/say/version.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+# Wrapper namespace module for a Say class
+module Mac
+  # A class wrapper around the MacOS `say` commad
+  # Allows to use simple TTS on Mac right from Ruby scripts
+  class Say
+    # mac-say version
+    VERSION = '0.1.0'
+  end
+end

data/mac-say.gemspec

@@ -0,0 +1,45 @@
+# -*- encoding: utf-8 -*-
+# frozen_string_literal: true
+
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'mac/say/version'
+
+Gem::Specification.new do |gem|
+  gem.name          = "mac-say"
+  gem.version       = Mac::Say::VERSION
+  gem.summary       = %q{Ruby wrapper around the macOS `say` command}
+  gem.description   = %q{Ruby wrapper around the modern version of the macOS `say` command. Inspired by the @bratta's mactts}
+  gem.license       = "MIT"
+  gem.authors       = ["Serge Bedzhyk"]
+  gem.email         = "smileart21@gmail.com"
+  gem.homepage      = "https://rubygems.org/gems/mac-say"
+
+  gem.files         = `git ls-files`.split($/)
+
+  `git submodule --quiet foreach --recursive pwd`.split($/).each do |submodule|
+    submodule.sub!("#{Dir.pwd}/",'')
+
+    Dir.chdir(submodule) do
+      `git ls-files`.split($/).map do |subpath|
+        gem.files << File.join(submodule,subpath)
+      end
+    end
+  end
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.require_paths = ['lib']
+
+  gem.add_development_dependency 'bundler', '~> 1.10'
+  gem.add_development_dependency 'minitest', '~> 5.0'
+  gem.add_development_dependency 'minitest-reporters', '~> 1.1'
+  gem.add_development_dependency 'rake', '~> 12.0'
+  gem.add_development_dependency 'simplecov', '~> 0.12'
+  gem.add_development_dependency 'rubygems-tasks', '~> 0.2'
+  gem.add_development_dependency 'yard', '~> 0.8.7.5'
+  gem.add_development_dependency 'inch', '~> 0.7.1'
+  gem.add_development_dependency 'redcarpet', '~> 3.4'
+  gem.add_development_dependency 'github-markup', '~> 1.4'
+  gem.add_development_dependency 'm', '~> 1.5'
+  gem.add_development_dependency 'coveralls', '~> 0.8'
+end

data/test/fake/say

@@ -0,0 +1,60 @@
+#! /usr/bin/env ruby
+# frozen_string_literal: true
+require 'optparse'
+
+VOICES = <<-VOICES
+Alex                en_US    # Most people recognize me by my voice.
+Daniel              en_GB    # Hello, my name is Daniel. I am a British-English voice.
+Fiona               en-scotland # Hello, my name is Fiona. I am a Scottish-English voice.
+Serena              en_GB    # Hello, my name is Serena. I am a British-English voice.
+Ting-Ting           zh_CN    # 您好，我叫Ting-Ting。我讲中文普通话。
+Veena               en_IN    # Hello, my name is Veena. I am an Indian-English voice.
+VOICES
+
+VOICES_NAMES = [
+  :alex,
+  :daniel,
+  :fiona,
+  :'ting-ting',
+  :veena
+]
+
+options = {
+  voice: :alex
+}
+
+OptionParser.new do |opts|
+  opts.banner = 'Usage: say [options]'
+
+  opts.on('-v VOICE') do |v|
+    options[:voice] = v.to_sym
+  end
+
+  opts.on('-r RATE') do |r|
+    options[:rate] = r.to_i
+  end
+
+  opts.on('-f FILE') do |f|
+    options[:file] = f
+  end
+end.parse!
+
+input = STDIN.read if !STDIN.tty? && !STDIN.closed?
+
+if options[:voice]
+  if options[:voice] == :'?'
+    print VOICES
+    exit 0
+  end
+  exit 1 unless VOICES_NAMES.include?(options[:voice])
+  exit 0 if input && !input.empty?
+end
+
+if options[:file]
+  file_path = options[:file]
+  file_path = File.absolute_path file_path, File.dirname(__FILE__)
+
+  File.exist?(file_path) ? exit(0) : exit(127)
+end
+
+exit 1

data/test/fixtures/text/en_gb.txt

@@ -0,0 +1,4 @@
+Alice had sat on the bank by her sister till she was tired.
+Once or twice she had looked at the book her sister held in her hand, but there were no pictures in it, "and what is the use of a book," thought Alice, "without pictures?"
+She asked herself as well as she could, for the hot day made her feel quite dull, if it would be worth while to get up and pick some daisies to make a chain.
+Just then a white rabbit with pink eyes ran close by her.

data/test/fixtures/text/en_gb_test.txt

@@ -0,0 +1 @@
+British English

data/test/fixtures/text/en_us.txt

@@ -0,0 +1,7 @@
+Atticus said to Jem one day, "I’d rather you shot at tin cans in the backyard, but I know you’ll go after birds.
+Shoot all the blue jays you want, if you can hit ‘em, but remember it’s a sin to kill a mockingbird."
+
+That was the only time I ever heard Atticus say it was a sin to do something, and I asked Miss Maudie about it.
+"Your father’s right," she said. "Mockingbirds don’t do one thing except make music for us to enjoy.
+They don’t eat up people’s gardens, don’t nest in corn cribs, they don’t do one thing but sing their hearts out
+for us. That’s why it’s a sin to kill a mockingbird.

data/test/fixtures/text/en_us_test.txt

@@ -0,0 +1 @@
+American English

data/test/helper.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+require 'rubygems'
+
+require 'coveralls'
+Coveralls.wear!
+
+begin
+  require 'bundler/setup'
+rescue LoadError => error
+  abort error.message
+end
+
+require 'simplecov'
+SimpleCov.start
+
+require 'minitest/autorun'
+require 'minitest/reporters'
+
+Minitest::Reporters.use! [
+  Minitest::Reporters::SpecReporter.new
+]

data/test/test_mac-say.rb

@@ -0,0 +1,227 @@
+# frozen_string_literal: true
+require 'helper'
+require 'mac/say'
+
+describe 'Mac::Say as a macOS `say` wrapper' do
+  describe 'On a class level' do
+    before do
+      @say_path = ENV['USE_FAKE_SAY'] ? ENV['USE_FAKE_SAY'] : '/usr/bin/say'
+    end
+
+    it 'must have a VERSION constant' do
+      Mac::Say.const_get('VERSION').wont_be_empty
+    end
+
+    it 'must return available voices as an Array of Hashes' do
+      Mac::Say.voices.wont_be_empty
+      Mac::Say.voices.must_be_kind_of Array
+    end
+
+    it 'must return specific Hash structure for a voice' do
+      voice = Mac::Say.voice(:name, :alex)
+      voice.wont_be_empty
+      voice.must_be_kind_of Hash
+      voice.keys.must_equal [:name, :iso_code, :sample]
+    end
+
+    it 'must return specific Hash structure for an iso_code' do
+      voice = Mac::Say.voice(:name, :alex)
+      voice.wont_be_empty
+      voice[:iso_code].must_be_kind_of Hash
+      voice[:iso_code].keys.must_equal [:language, :country]
+    end
+
+    it '.voice must search for a voice by name' do
+      voice = Mac::Say.voice(:name, :alex)
+      voice[:name].must_equal :alex
+    end
+
+    it '.voice must search for a voice by country' do
+      voice = Mac::Say.voice(:country, :scotland)
+      voice[:name].must_equal :fiona
+    end
+
+    it '.voice must search for a voice by language' do
+      voices = Mac::Say.voice(:language, :en)
+      voices.count.must_be :>, 2
+    end
+
+    it '.voice must return one voice as a Hash' do
+      voice = Mac::Say.voice(:name, :alex)
+      voice.must_be_kind_of Hash
+    end
+
+    it '.voice must return an Array of voices if > 1' do
+      voices = Mac::Say.voice(:country, :gb)
+      voices.must_be_kind_of Array
+    end
+
+    it ".voice must return nil if voice wasn't found" do
+      voices = Mac::Say.voice(:name, :xxx)
+      voices.must_be_nil
+    end
+
+    it '.say must return 0 in successive speech' do
+      expectation = ["#{@say_path} -v 'alex' -r 175", 0]
+      Mac::Say.say('42').must_equal expectation
+    end
+
+    it '.say must use custom voice' do
+      expectation = ["#{@say_path} -v 'alex' -r 175", 0]
+      Mac::Say.say('42', :alex).must_equal expectation
+    end
+
+    it '.say must work with multiple lines' do
+      expectation = ["#{@say_path} -v 'alex' -r 175", 0]
+      Mac::Say.say(<<-TEXT, :alex).must_equal expectation
+        1
+        2
+        3
+      TEXT
+    end
+
+    it '.say must fail on wrong voice' do
+      -> {
+        Mac::Say.say 'OMG! I lost my voice!', :wrong
+      }.must_raise Mac::Say::VoiceNotFound
+    end
+
+    it '.voice must fail on wrong voice feature' do
+      -> {
+        Mac::Say.voice(:tone, :enthusiastic)
+      }.must_raise Mac::Say::UnknownVoiceFeature
+    end
+  end
+
+  describe "On an instance level" do
+    before do
+      @reader   = Mac::Say.new
+      @say_path = @reader.config[:say_path]
+    end
+
+    it 'must instantiate Mac::Say' do
+      @reader.must_be_instance_of Mac::Say
+    end
+
+    it '#say must return 0 on successive speech' do
+      expectation = ["#{@say_path} -v 'alex' -r 175", 0]
+      @reader.say(string: '42').must_equal expectation
+    end
+
+    it '#read must be a synonym of #say' do
+      expectation = ["#{@say_path} -v 'alex' -r 175", 0]
+      @reader.read(string: '42').must_equal expectation
+    end
+
+    it '#say must support :file' do
+      absolute_path = File.absolute_path './fixtures/text/en_gb_test.txt', File.dirname(__FILE__)
+      expectation = ["#{@say_path} -f #{absolute_path} -v 'alex' -r 175", 0]
+
+      @reader.say(file: absolute_path).must_equal expectation
+    end
+
+    it '#say must read :file from initial config' do
+      absolute_path = File.absolute_path './fixtures/text/en_gb_test.txt', File.dirname(__FILE__)
+      expectation = ["#{@say_path} -f #{absolute_path} -v 'alex' -r 175", 0]
+
+      @reader = Mac::Say.new(file: absolute_path)
+      @reader.say.must_equal expectation
+    end
+
+    it '#say must change :file from initial config' do
+      gb_absolute_path = File.absolute_path './fixtures/text/en_gb_test.txt', File.dirname(__FILE__)
+      us_absolute_path = File.absolute_path './fixtures/text/en_us_test.txt', File.dirname(__FILE__)
+
+      expectation = ["#{@say_path} -f #{us_absolute_path} -v 'alex' -r 175", 0]
+
+      # init
+      @reader = Mac::Say.new(file: gb_absolute_path)
+      @reader.config[:file].must_equal gb_absolute_path
+
+      # change
+      @reader.say(file: us_absolute_path).must_equal expectation
+      @reader.config[:file].must_equal us_absolute_path
+    end
+
+    it '#say must prioritise :file over :string' do
+      absolute_path = File.absolute_path './fixtures/text/en_gb_test.txt', File.dirname(__FILE__)
+      expectation = ["#{@say_path} -f #{absolute_path} -v 'alex' -r 175", 0]
+
+      @reader.say(string: 'test', file: absolute_path).must_equal expectation
+    end
+
+    it '#say must support custom :rate' do
+      expectation = ["#{@say_path} -v 'alex' -r 250", 0]
+      @reader.say(string: '42', rate: 250).must_equal expectation
+    end
+
+    it '#say must support custom :voice' do
+      expectation = ["#{@say_path} -v 'fiona' -r 175", 0]
+      @reader.say(string: '42', voice: :fiona).must_equal expectation
+    end
+
+    it '#say must change the :voice' do
+      expectation = ["#{@say_path} -v 'fiona' -r 175", 0]
+      @reader.config[:voice].must_equal :alex
+
+      @reader.say(string: '42', voice: :fiona).must_equal expectation
+      @reader.config[:voice].must_equal :fiona
+
+      @reader.say(string: '13').must_equal expectation
+    end
+
+    it '#say must change the :rate' do
+      expectation = ["#{@say_path} -v 'alex' -r 300", 0]
+      @reader.config[:rate].must_equal 175
+
+      @reader.say(string: '42', rate: 300).must_equal expectation
+      @reader.config[:rate].must_equal 300
+
+      @reader.say(string: '13').must_equal expectation
+    end
+
+    it '#say must fail on wrong initial voice' do
+      -> {
+        talker = Mac::Say.new(voice: :wrong)
+        talker.say string: 'OMG! I lost my voice!'
+      }.must_raise Mac::Say::VoiceNotFound
+    end
+
+    it '#say must fail on wrong dynamic voice' do
+      -> {
+        talker = Mac::Say.new
+        talker.say string: 'OMG! I lost my voice!', voice: :wrong
+      }.must_raise Mac::Say::VoiceNotFound
+    end
+
+    it '#voice must fail on wrong say path' do
+      -> {
+        Mac::Say.new(say_path: '/wrong/wrong/path').voice(:name, :alex)
+      }.must_raise Mac::Say::CommandNotFound
+    end
+
+    it '#say must fail on wrong say path' do
+      -> {
+        Mac::Say.new(say_path: '/wrong/wrong/path').say 'test'
+      }.must_raise Mac::Say::CommandNotFound
+    end
+
+    it '#say must fail on wrong file path' do
+      -> {
+        Mac::Say.new.say(file: '/wrong/wrong/path')
+      }.must_raise Mac::Say::FileNotFound
+    end
+
+    it '#voice must fail on wrong feature' do
+      -> {
+        Mac::Say.new.voice(:articulation, :nostalgic)
+      }.must_raise Mac::Say::UnknownVoiceFeature
+    end
+
+    it '#say must fail on initial wrong file path' do
+      -> {
+        Mac::Say.new(file: '/wrong/wrong/path').say
+      }.must_raise Mac::Say::FileNotFound
+    end
+  end
+end