Optional phone voice models v1 — manual installation

Voice commands

Player controls

Open Settings > Voice commands on either Humanoid or YOS.
The Voice commands section lets players enable recognition, select an available language,
change the activation keyword, or restore that language's default keyword. Wait for Ready,
hold the normal in-game talk key, speak a displayed phrase, and release the key.
Examples include phone open, phone close, abre el teléfono and cierra el teléfono.
The testing /phonevoice commands have been removed.

Only one model is loaded at a time. Language and per-language keyword preferences are saved
locally per client/resource, independently of the phone's display language and character.
Changing language or keyword cancels pending recognition and releases the previous model.
Disabling the feature releases the microphone and recognizer. Nearby players still hear
spoken commands through normal voice chat.

Default English commands

Use your configured keyword in place of phone:

• phone open / phone close: show or hide the phone.
• phone answer / phone decline: answer an incoming voice call or decline an incoming call.
• phone hang up: end an ongoing call.
• phone flashlight on / phone flashlight off: set the flashlight state.
• phone camera / phone contacts / phone messages: open the app after unlocking if required.
• phone mute / phone sound: mute phone sounds or restore sound (not the call microphone).

Sound restores the current positive volume, or 50% when volume is zero. App commands do not
interrupt calls, the camera or live broadcasts. Existing saved admin configurations retain
their commands; add new defaults through the dashboard after restarting to refresh the functions.

Server-owner controls

The admin dashboard's Voice commands page manages the global switch, default language,
available configured languages, keyword defaults, confidence, localized phrases, rejection
phrases, and command enable/disable/add/edit/delete. Each command references a function
from a dropdown containing the startup Lua action catalog. Admin access is permission-gated.
Phrase and language configuration saves apply live; players reload their selected profile.
If a selected language is disabled or removed, the server default is selected instead.

config/config.voiceCommands.lua seeds the first configuration. Admin saves are persisted
in server/custom/voiceCommands.runtime.json and override that seed after restart, except
Config.VoiceCommands.Enabled = false always disables the feature. That switch hides the
entire settings entry on both phone systems, blocks stale navigation and stops recognition. Back up
this file when updating the resource. To deliberately reset all admin changes, stop the
resource, remove the runtime JSON, and start it again. The runtime JSON is server-only.

Adding custom actions after release

No separate resource or UI rebuild is required. Add functions to the single editable file
server/custom/functions/voiceCommandActions.lua, inside YSeriesVoiceActions:

show_help = function(playerSource)
    TriggerClientEvent('ox_lib:notify', playerSource, {
        title = 'Phone', description = 'Your custom help text.', type = 'info'
    })
    return true, 'Help shown'
end,

Restart yseries. The new show_help function then appears in the admin dropdown. Create a
command, choose that function, and enter English {keyword} help and Spanish {keyword} ayuda
phrases. Save the configuration. No runtime code parsing, registration or Lua execution from
the dashboard occurs. Editing or adding a function requires another resource restart.
Functions receive the invoking player's source and return true or false, 'Reason'.
Perform all permissions, ownership and gameplay validation inside the function. A client can
forge a command request, so speech detection must never grant permissions by itself.

Default open and close server actions dispatch built-in client behavior from
client/custom/functions/voiceCommandHandlers.lua, preserving the phone's usual guards.
For other client behavior, a custom server action can send your explicitly named client event;
implement that event in the existing editable client/custom area.

{keyword} expands to the player's selected keyword. Literal phrases without that token are
unchanged by keyword edits. Multiple aliases per language are supported; omit a language to
exclude that command there. Duplicate phrases across actions and overlaps with rejection
phrases are rejected. Server execution checks enabled commands, language, revision and cooldown.
Limits: 8 languages, 64 commands, 16 aliases per command/language and 128 total phrases
including rejection phrases. Action IDs use lowercase letters, numbers and underscores.

Languages and models

Models are not bundled with the phone. Download them manually from the
optional model downloads and setup guide.
The phone never downloads an external model automatically.

1. Download English vosk-model-small-en-us-0.15.tar.gz.
2. Upload that file without extracting or renaming it to
   yseries/ui/build/voice/vosk-model-small-en-us-0.15.tar.gz.
   For standalone YPhone use yphone/ui/build/voice/; for standalone YFlip use
   yflip-phone/ui/build/voice/. Use your actual phone resource folder if renamed.
   Do not put it in the props resource.
3. Keep Config.VoiceCommands.Enabled = true, DefaultLanguage = 'en', and the English
   ModelUrl = 'voice/vosk-model-small-en-us-0.15.tar.gz' in config/config.voiceCommands.lua.
   If you already saved dashboard settings, select/enable English there too.
4. Restart your phone resource (restart yseries, restart yphone, or restart yflip-phone).
   Players open Settings > Voice commands on either YOS or Humanoid,
   choose English and enable recognition. Wait for Ready, then hold the talk key and say
   phone open. Players cannot install server files; send this guide to the server owner.

English SHA-256: 80bd593276e4bdd46223ae7649066d1e5a0ce3be1281490abc68c3cab19f6990 (41,160,778 bytes).

Spanish profiles and saved preferences remain supported. Install the optional
Spanish vosk-model-small-es-0.42.tar.gz
unchanged in the same ui/build/voice/ directory before selecting Spanish. Its SHA-256 is
d9b03fceb51a05d71f0bd648cccc2e5eb80f3f3ac39d65fe60f95fc698c8a54c (39,799,547 bytes).
Owners offering only English can disable Spanish in the dashboard. A missing selected model
shows setup guidance and cannot start recognition.

For other languages, use a small Vosk model with dynamic vocabulary support. The official
Vosk downloads commonly provide ZIP files, which are
not loader-compatible. Extract the ZIP outside the resource, then run
tar -czf my-model.tar.gz model-folder from the directory containing the extracted folder.
The archive must contain one model folder with am/final.mdl, conf/model.conf,
conf/mfcc.conf, the graph files and any ivector files beneath it. Renaming a ZIP is not
conversion. Preserve the model's license. Add a language profile with Label, ModelUrl,
Keyword and RejectionPhrases, restart, then enable its translated commands in the dashboard.
Custom local voice/*.tar.gz filenames remain supported; remote URLs were not supported
by the server configuration and are not enabled by this change.

Source builds: keep all model archives backed up outside ui/public, ui/build and
release staging. Run npm ci and npm run build in ui, then upload the models to
ui/build/voice/ again. Rebuilding replaces ui/build. The build rejects archives placed
in ui/public/voice, and release packaging excludes model binaries even if stale files
remain in an input folder. Do not add models to the distributable source ZIP.

Recognition runs locally with vosk-browser; no audio or transcripts are uploaded. Only action
IDs, language and configuration revision are sent to the server. Adding phrases does not
train new words; keywords must exist in the selected model. Both optional models use Apache
License 2.0. Their original files are unchanged, repackaged as tar.gz for vosk-browser.
Attribution and license are in ui/build/voice/NOTICE.txt and LICENSE-2.0.txt, and in the
optional download release.

Runtime and troubleshooting

Settings checks the selected server file before loading the recognizer. Missing files show
setup guidance; unreadable files or network failures show an availability error; an invalid
gzip header shows an invalid model error. A valid header only confirms the file can be tried:
corrupt archives or incompatible model contents can still fail during loading. There is no
automatic retry loop. After installing or correcting the file, restart the resource and
reopen Settings. If it still fails, check exact filename/case, directory, upload size/hash,
file permissions and the configured ModelUrl. A missing file cannot be fixed by changing
microphone permissions. Settings also shows startup, readiness and errors. Idle mic/talking logs and test commands are
removed. Check microphone permissions/device if startup fails. The existing
nearbyAudio:talking event gates capture; IsPlayerTalking() in
client/custom/functions/misc.lua must reflect the installed voice plugin correctly.
The mic stays ready while enabled, with 500 ms pre-roll and a 500 ms release grace period.
Utterances over eight seconds are discarded. Only complete supported phrases meeting the
per-word confidence threshold (default 0.60) execute. Restricted grammar confidence does not
guarantee intent; test with actual player voices and normal conversation on your server.

Escrow and updates

config/**/*, server/custom/**/*.lua, client/custom/**/*.lua and ui/build/voice/**/*
remain outside escrow. Keep the action file, runtime JSON and any added models when updating.
The compiled phone UI receives its vocabulary dynamically and needs no rebuild for new phrases.