scansion 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,401 @@
1
+ #!/usr/bin/env ruby
2
+ # frozen_string_literal: true
3
+
4
+ require "ffi"
5
+
6
+ # Remplacement « drop-in » du wrapper CLI d'espeak-ng, appelant la bibliothèque
7
+ # C d'espeak-ng directement via FFI — aucun processus engendré par mot.
8
+ #
9
+ # apt install libespeak-ng-dev # Debian/Ubuntu
10
+ # brew install espeak-ng # macOS (la lib est keg-only, voir ci-dessous)
11
+ #
12
+ # Si la bibliothèque vit hors du chemin de recherche par défaut (p. ex.
13
+ # installation Homebrew keg-only), définir PHONEMIZER_ESPEAK_LIB dans
14
+ # l'environnement avant de charger ce fichier :
15
+ #
16
+ # ENV["PHONEMIZER_ESPEAK_LIB"] =
17
+ # %x(brew --prefix espeak-ng).strip + "/lib/libespeak-ng.dylib"
18
+ #
19
+ # Contrat du backend (vérifié contre libespeak-ng 1.1.51) :
20
+ # espeak_TextToPhonemes traduit une *clause* par appel — le texte jusqu'à
21
+ # une virgule, un point-virgule, deux-points, un point ou terminateur
22
+ # similaire — en avançant son pointeur de texte et en renvoyant NULL en fin
23
+ # d'entrée. Les mots d'une même clause s'influencent (liaisons, consonnes
24
+ # finales prononcées).
25
+ #
26
+ # Différence IMPORTANTE avec le binaire CLI : la fonction n'offre AUCUNE
27
+ # isolation entre les morceaux concaténés — les sauts de ligne ne sont que
28
+ # des espaces et les morceaux adjacents fusionnent. Grouper plusieurs mots
29
+ # dans un même tampon corromprait donc silencieusement les résultats ; chaque
30
+ # morceau a son propre appel. C'est un appel de fonction en processus, bien
31
+ # moins coûteux que le fork+exec par mot du CLI.
32
+ #
33
+ # --ipa correspond au bit 1 de phonememode (0x02) ; --sep aux bits 8-23. Le
34
+ # pipeline phonemize demande toujours l'octet sentinelle \x01 comme
35
+ # séparateur inter-phones, donc n'importe quel phone_sep utilisateur
36
+ # (multi-caractères, espaces, « - ») se reporte sur la sortie sans risque de
37
+ # collision ; espeak_raw, lui, transmet les séparateurs d'un seul octet tels
38
+ # quels, comme --sep.
39
+ #
40
+ # Sélection de voix calquée sur le CLI : espeak_SetVoiceByName reconnaît les
41
+ # voix installées (« en-us ») ; les codes qu'il ne connaît pas (« fr-fr »
42
+ # quand seul « fr » est installé) retombent sur espeak_SetVoiceByProperties
43
+ # avec les critères de langue — exactement ce que fait le CLI espeak-ng en
44
+ # interne.
45
+ module Phonemizer
46
+ module_function
47
+
48
+ DEFAULT_LANGUAGE = "en-us"
49
+
50
+ # Conservé pour la compatibilité d'API avec le wrapper CLI. Les appels en
51
+ # processus sont bon marché et libespeak-ng n'est pas thread-safe : il n'y a
52
+ # donc rien à mettre en pool.
53
+ DEFAULT_WORKERS = 1
54
+
55
+ # espeak émet des balises de langue entre parenthèses lors des changements de
56
+ # langue, p. ex. (en) / (fr) / (pt-br) ; le motif couvre toute balise qu'espeak
57
+ # peut émettre.
58
+ LANG_SWITCH = /\((?:[a-z]{2,3}(?:-[a-z0-9]+)*)\)/
59
+
60
+ # Caractères qu'espeak chercherait à prononcer ; on les découpe à la place.
61
+ # Les apostrophes sont EXCLUES exprès : elles doivent rester à l'intérieur du
62
+ # mot qu'elles élident (aujourd'hui, l'instar). Les couper transcrirait les
63
+ # deux moitiés séparément et perdrait les consonnes de liaison
64
+ # (oʒuʁdɥi -> oʒuʁ + yi).
65
+ PUNCT = /([[:punct:]&&[^'’‘]]+)/
66
+
67
+ # Cache partagé par les fonctions du module. Une constante (pas un @ivar)
68
+ # pour que les méthodes fonctionnent pareil appelées via
69
+ # Phonemizer.phonemize(...) ou après `include Phonemizer` — les copies
70
+ # module_function ne portent pas le contexte de variable d'instance du module.
71
+ CACHE = {}
72
+
73
+ # ---------------------------------------------------------------- FFI
74
+
75
+ module LibEspeak
76
+ extend FFI::Library
77
+
78
+ ffi_lib [ENV["PHONEMIZER_ESPEAK_LIB"], "libespeak-ng.so.1",
79
+ "libespeak-ng.so", "libespeak-ng.dylib"].compact
80
+
81
+ AUDIO_OUTPUT_SYNCHRONOUS = 2 # pas de sortie audio, pas de file asynchrone
82
+ CHARS_UTF8 = 1 # espeakCHARS_UTF8
83
+ INITIALIZE_DONT_EXIT = 0x8000 # valeur de retour d'erreur au lieu de exit()
84
+ PHONEME_IPA = 0x02 # bit 1 de phonememode : sortie IPA
85
+
86
+ EE_OK = 0
87
+ EE_INTERNAL_ERROR = -1
88
+
89
+ # Séparateur inter-phones sentinelle demandé à espeak (encodé dans les bits
90
+ # 8-23 de phonememode). \x01 n'apparaît jamais dans la sortie IPA, donc le
91
+ # reporter ensuite sur le phone_sep de l'utilisateur ne peut pas entrer en
92
+ # collision, quel que soit le phone_sep (multi-caractères, espaces, même « - »).
93
+ SEP_CHAR = "\x01"
94
+
95
+ attach_function :espeak_Initialize, %i[int int pointer int], :int
96
+ attach_function :espeak_SetVoiceByName, [:string], :int
97
+ attach_function :espeak_SetVoiceByProperties, [:pointer], :int
98
+ attach_function :espeak_TextToPhonemes, %i[pointer int int], :string
99
+
100
+ # espeak_VOICE — seuls les champs renseignés ; le reste reste à zéro.
101
+ # NOTE : FFI interdit d'ASSIGNER les champs :string en ligne (ce sont des
102
+ # raccourcis en lecture seule pour char*). Les membres char* sont donc
103
+ # déclarés :pointer et alimentés par un MemoryPointer contenant une chaîne
104
+ # terminée par NUL (voir with_voice).
105
+ class Voice < FFI::Struct
106
+ layout :name, :pointer, :languages, :pointer, :identifier, :pointer,
107
+ :gender, :uint8, :age, :uint8, :variant, :uint8, :xx1, :uint8,
108
+ :score, :int, :spare, :pointer
109
+ end
110
+
111
+ # phonememode : toujours de l'IPA ; séparateur sentinelle seulement en mode
112
+ # sep. Utilisé par le pipeline phonemize (stitch reporte la sentinelle ensuite).
113
+ module_function
114
+
115
+ def phonememode(phone_sep)
116
+ mode = PHONEME_IPA
117
+ mode |= (SEP_CHAR.ord << 8) unless phone_sep.empty?
118
+ mode
119
+ end
120
+
121
+ # espeak_Initialize doit tourner une fois avant toute chose. Idempotent.
122
+ # AUDIO_OUTPUT_SYNCHRONOUS : aucun périphérique audio n'est touché ;
123
+ # DONT_EXIT fait d'un espeak-ng-data manquant une erreur de retour plutôt
124
+ # qu'un exit() brutal.
125
+ def init!
126
+ return true if @initialized
127
+ rate = espeak_Initialize(AUDIO_OUTPUT_SYNCHRONOUS, 0, nil,
128
+ INITIALIZE_DONT_EXIT)
129
+ if rate == EE_INTERNAL_ERROR
130
+ raise "échec d'espeak_Initialize : espeak-ng-data est-il installé ?"
131
+ end
132
+ @initialized = true
133
+ end
134
+ end
135
+
136
+ # ---------------------------------------------------------------- API publique
137
+
138
+ # Entrée : une String (un énoncé) ou un Array de mots.
139
+ # Retourne une String (ou un Array de Strings, à la forme de l'entrée).
140
+ #
141
+ # Options :
142
+ # language: voix espeak, défaut « en-us »
143
+ # phone_sep: inséré entre les phones, défaut « » (mɑ̃ʒe)
144
+ # word_sep: joint les énoncés multi-mots, défaut « »
145
+ # strip_stress: retire ˈ ˌ de la sortie, défaut true
146
+ # language_switch: :remove (défaut) ou :keep
147
+ # workers: accepté, ignoré (conservé pour la compatibilité d'API ;
148
+ # la bibliothèque est appelée en processus et n'est pas
149
+ # thread-safe)
150
+ def phonemize(words, language: DEFAULT_LANGUAGE, phone_sep: "",
151
+ word_sep: " ", strip_stress: true, language_switch: :remove,
152
+ workers: nil)
153
+ if words.is_a?(Array)
154
+ phonemize_batch(words, language:, phone_sep:, word_sep:,
155
+ strip_stress:, language_switch:)
156
+ else
157
+ phonemize_batch([words], language:, phone_sep:, word_sep:,
158
+ strip_stress:, language_switch:).first
159
+ end
160
+ end
161
+
162
+ def clear_cache
163
+ CACHE.clear
164
+ end
165
+
166
+ # Compatibilité wrapper CLI : transcription brute d'un énoncé. Renvoie l'IPA
167
+ # brute (accents de stress, tirets de liaison et balises de langue intacts).
168
+ #
169
+ # Calque l'espeak_raw du gem, où --sep=<car> fait séparer les phones par
170
+ # espeak lui-même avec le caractère de l'utilisateur (les frontières de mot
171
+ # sortent en double espace en mode sep). Les séparateurs d'un octet sont
172
+ # transmis tels quels via les bits 8-23 de phonememode — le même réglage que
173
+ # tourne le --sep du CLI — vérifié pour produire une sortie identique octet
174
+ # par octet pour sep=" ".
175
+ # Les séparateurs multi-octets sont inexpressibles au niveau d'espeak (le
176
+ # champ fait un octet ; --sep a la même limite), donc ils retombent sur la
177
+ # sentinelle puis sont substitués ; la sortie brute ne diffère alors du CLI
178
+ # que par des frontières de mot espacées une seule fois.
179
+ #
180
+ # Le saut de ligne final du CLI (espeak imprime une ligne entière) n'est pas
181
+ # reproduit ; tous les consommateurs de cette valeur, dans les deux
182
+ # implémentations, retirent les espaces autour avant usage.
183
+ def espeak_raw(text, language, phone_sep: nil)
184
+ with_voice(language) do
185
+ text = text.to_s
186
+ sep = phone_sep.to_s
187
+
188
+ out =
189
+ if sep.empty?
190
+ transcribe_piece(text, LibEspeak::PHONEME_IPA)
191
+ elsif sep.bytesize == 1
192
+ # Parité CLI : transmettre l'octet du séparateur dans les bits 8-23
193
+ # de phonememode, exactement ce que fait --sep=<car> au niveau d'espeak.
194
+ mode = LibEspeak::PHONEME_IPA | (sep.getbyte(0) << 8)
195
+ transcribe_piece(text, mode)
196
+ else
197
+ # Séparateur multi-octets : impossible au niveau d'espeak.
198
+ # Transcrire avec la sentinelle, puis substituer le séparateur de
199
+ # l'utilisateur.
200
+ out = transcribe_piece(text, LibEspeak.phonememode(sep))
201
+ out.gsub(LibEspeak::SEP_CHAR, sep)
202
+ end
203
+
204
+ warn "ATTENTION : espeak-ng n'a rien renvoyé pour : #{text[0, 40].inspect}" \
205
+ if out.strip.empty? && !text.strip.empty?
206
+
207
+ out
208
+ end
209
+ end
210
+
211
+ # ---------------------------------------------------------------- pipeline
212
+
213
+ def phonemize_batch(words, language:, phone_sep:, word_sep:,
214
+ strip_stress:, language_switch:)
215
+ # Garde-fou pour nil : ne copier que si un élément n'est pas déjà une String
216
+ words = words.map(&:to_s) unless words.all? { |w| w.is_a?(String) }
217
+
218
+ # Cache : les formes de mots se répètent constamment dans un lexique. Les
219
+ # options sont fixées pour tout l'appel, donc la clé est une fonction pure
220
+ # du mot — on la mémoïse pour ne construire chaque tableau de clé qu'une
221
+ # fois par mot unique.
222
+ key_of = Hash.new do |h, w|
223
+ h[w] = [w, language, phone_sep, word_sep, strip_stress, language_switch]
224
+ end
225
+ todo = words.uniq.reject { |w| CACHE.key?(key_of[w]) }
226
+
227
+ unless todo.empty?
228
+ with_voice(language) do
229
+ # Ponctuation : découper les énoncés sur la ponctuation, ne transcrire
230
+ # que les morceaux propres, puis remettre la ponctuation en place
231
+ chunks = todo.map { |w| split_punctuation(w) }
232
+
233
+ mode = LibEspeak.phonememode(phone_sep)
234
+ clean_words = chunks.flatten.reject { |p| PUNCT.match?(p) }.uniq
235
+ ipa_map = clean_words.each_with_object({}) do |piece, map|
236
+ map[piece] = transcribe_piece(piece, mode)
237
+ end
238
+
239
+ todo.each_with_index do |w, i|
240
+ CACHE[key_of[w]] = stitch(chunks[i], ipa_map,
241
+ phone_sep:, word_sep:, strip_stress:,
242
+ language_switch:)
243
+ end
244
+ end
245
+ end
246
+
247
+ words.map { |w| CACHE[key_of[w]] }
248
+ end
249
+
250
+ # énoncé -> [ponct, mot, ponct, mot, ...]
251
+ def split_punctuation(word)
252
+ word.split(PUNCT).reject(&:empty?)
253
+ end
254
+
255
+ # Reassemble un énoncé : ponctuation remise en place, séparateurs appliqués.
256
+ # ipa_map associe à chaque morceau sa transcription IPA brute (indexée par
257
+ # le contenu).
258
+ def stitch(parts, ipa_map, phone_sep:, word_sep:, strip_stress:,
259
+ language_switch:)
260
+ parts.map do |part|
261
+ next part if PUNCT.match?(part) # ponctuation : telle quelle
262
+ t = ipa_map[part] || ""
263
+ t = t.gsub(LANG_SWITCH, "") if language_switch == :remove
264
+ # Toujours retirer les accents de stress ; ne retirer le tiret de liaison
265
+ # qu'en mode contigu, où espeak l'émet (p. ex. « les amis » -> « le-z
266
+ # ami »). En mode sep, on a transcrit avec la sentinelle, donc un « - »
267
+ # de l'utilisateur dans phone_sep doit survivre.
268
+ if strip_stress
269
+ t = t.delete("ˈˌ")
270
+ t = t.delete("-") if phone_sep.empty?
271
+ end
272
+ if phone_sep.empty?
273
+ # phones contigus : un simple espace est une frontière de mot
274
+ t = t.gsub(" ", word_sep)
275
+ else
276
+ # Mode sep : la sentinelle \x01 sépare les phones, un simple espace
277
+ # marque une frontière de mot. Report en une passe, donc phone_sep et
278
+ # word_sep peuvent contenir N'IMPORTE quels caractères — y compris des
279
+ # espaces — sans collision.
280
+ t = t.gsub(/[\x01 ]/) do |ch|
281
+ ch == LibEspeak::SEP_CHAR ? phone_sep : word_sep
282
+ end
283
+ end
284
+ t
285
+ end.join
286
+ end
287
+
288
+ # ---------------------------------------------------------------- internes
289
+
290
+ # La sélection de voix de libespeak-ng est un état global ; la définir avant
291
+ # de transcrire. Initialisation garantie : tout point d'entrée passe par ici.
292
+ #
293
+ # Calque le CLI d'espeak-ng : SetVoiceByName reconnaît les voix et variantes
294
+ # installées ; les codes de langue purs qu'il ne connaît pas (« fr-fr » sur
295
+ # un système qui n'installe que « fr ») retombent sur SetVoiceByProperties,
296
+ # qui correspond sur la langue (plus le dialecte) seule.
297
+ #
298
+ # Le champ languages doit être un char* terminé par NUL : la coercition
299
+ # :string de Ruby ne s'applique qu'aux ARGUMENTS de fonction, pas aux champs
300
+ # de struct, et les champs :string d'une struct sont en lecture seule en FFI —
301
+ # d'où le MemoryPointer explicite ici. `lang` est gardé vivant sur la pile
302
+ # locale pendant toute la durée de l'appel, ce qui satisfait l'exigence de
303
+ # durée de vie de la struct.
304
+ def with_voice(language)
305
+ LibEspeak.init!
306
+ rc = LibEspeak.espeak_SetVoiceByName(language)
307
+ if rc != LibEspeak::EE_OK
308
+ lang = FFI::MemoryPointer.from_string(language) # terminée par NUL
309
+ spec = LibEspeak::Voice.new
310
+ spec[:languages] = lang
311
+ rc = LibEspeak.espeak_SetVoiceByProperties(spec)
312
+ end
313
+ unless rc == LibEspeak::EE_OK
314
+ raise "espeak-ng : impossible de sélectionner la voix #{language.inspect}"
315
+ end
316
+
317
+ yield
318
+ end
319
+
320
+ # Transcrit un morceau avec le phonememode donné. Un morceau ne contient
321
+ # normalement qu'une seule clause (la ponctuation a été découpée en amont),
322
+ # mais on continue à vider les clauses par précaution : un terminateur
323
+ # parasite serait sinon silencieusement perdu, et joindre les fragments
324
+ # garde un résultat sain.
325
+ #
326
+ # Les fragments de clause sont joints par un simple espace, comme la sortie
327
+ # IPA sur une ligne du CLI (« mots séparés par des espaces sur une ligne,
328
+ # dans l'ordre d'entrée » — l'API C les délivre juste une clause à la fois).
329
+ def transcribe_piece(piece, mode)
330
+ buf = FFI::MemoryPointer.from_string(piece)
331
+ tp = FFI::MemoryPointer.new(:pointer)
332
+ tp.write_pointer(buf)
333
+
334
+ clauses = []
335
+ while (clause = LibEspeak.espeak_TextToPhonemes(
336
+ tp, LibEspeak::CHARS_UTF8, mode
337
+ ))
338
+ clauses << clause
339
+ break if tp.read_pointer.null?
340
+ end
341
+ # FFI renvoie des chaînes ASCII-8BIT ; la charge IPA est en UTF-8.
342
+ clauses.join(" ").strip.force_encoding(Encoding::UTF_8)
343
+ end
344
+ end
345
+
346
+ # ---------------------------------------------------------------------------
347
+ # Mode exécutable : calque le bin/phonemize du gem pour que ce fichier unique
348
+ # serve à la fois de bibliothèque et de commande. Ne tourne que s'il est invoqué
349
+ # directement (ruby phonemizer_ffi.rb ... ou via un lien/execbit), donc le
350
+ # charger depuis ailleurs reste sans effet de bord.
351
+ #
352
+ # Différences avec le bin/phonemize du gem, toutes imposées par le backend :
353
+ # * pas de flag --workers/-j (backend FFI monothread)
354
+ # * mode stdin ajouté : le CLI n'a pas d'interface batch sur stdin, et la
355
+ # bibliothèque n'a pas de pool de workers, donc les lignes depuis stdin
356
+ # sont la voie naturelle à haut débit pour ce backend.
357
+ if $PROGRAM_NAME == __FILE__
358
+ require "optparse"
359
+
360
+ options = {
361
+ language: Phonemizer::DEFAULT_LANGUAGE,
362
+ phone_sep: "",
363
+ word_sep: " ",
364
+ strip_stress: true,
365
+ language_switch: :remove
366
+ }
367
+
368
+ parser = OptionParser.new do |o|
369
+ o.banner = "Utilisation : #{File.basename($PROGRAM_NAME)} [options] [texte | fichier]"
370
+ o.on("-l", "--language LANG",
371
+ "voix espeak (défaut : #{Phonemizer::DEFAULT_LANGUAGE})") { |v| options[:language] = v }
372
+ o.on("-p", "--phone-sep SEP",
373
+ "séparateur entre phones (défaut : aucun)") { |v| options[:phone_sep] = v }
374
+ o.on("-w", "--word-sep SEP",
375
+ "séparateur entre les mots d'un même énoncé (défaut : espace)") { |v| options[:word_sep] = v }
376
+ o.on("-s", "--[no-]strip-stress",
377
+ "retirer les accents de stress et les tirets de liaison (défaut : oui)") { |v| options[:strip_stress] = v }
378
+ o.on("-k", "--keep-language-switch",
379
+ "garder les balises de langue (en)/(fr) en ligne (défaut : les retirer)") { options[:language_switch] = :keep }
380
+ o.on("-h", "--help", "afficher cette aide") do
381
+ puts o
382
+ exit
383
+ end
384
+ end
385
+ parser.parse!(ARGV)
386
+
387
+ # Mode batch stdin : une ligne = un énoncé, transcrit en un seul lot.
388
+ if ARGV.empty? && !$stdin.tty?
389
+ lines = $stdin.read.lines.map(&:strip).reject(&:empty?)
390
+ exit if lines.empty?
391
+ Phonemizer.phonemize(lines, **options).each { |line| puts line }
392
+ else
393
+ text = ARGV.join(" ")
394
+ if File.file?(text)
395
+ lines = File.readlines(text, chomp: true).reject(&:empty?)
396
+ Phonemizer.phonemize(lines, **options).each { |line| puts line }
397
+ else
398
+ puts Phonemizer.phonemize(text, **options)
399
+ end
400
+ end
401
+ end
@@ -0,0 +1,5 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Scansion
4
+ VERSION = '0.1.0'
5
+ end