[voice] Restructure the org.openhab.core.voice package

[florian-h05]

The org.openhab.core.voice package is really "crowded" and unorganised as of now:

Before taking further action on it with refactoring the DialogProcessor/VoiceManagerImpl into smaller classes, or adding new features, it'd good to clean up that mess:

This doesn't change any functionality, and openhab/openhab-addons#21476 adjusts the add-ons accordingly.

[florian-h05]

@openhab/core-maintainers Can you please remove the "work in progress label"? Thanks!

[Copilot]

Pull request overview

Restructures the voice APIs into dedicated dialog, STT, TTS, and text packages while updating consumers and tests.

Changes:

• Relocates voice interfaces, events, exceptions, dialog types, and cache implementations.
• Updates internal, REST, scripting, and test references.
• Removes the grammars parameter from STTService.recognize().

Outstanding comments:

• Critical: Add the STT, TTS, and keyword-spotting subpackages to model.script’s Import-Package.
• Critical: Preserve or migrate DialogRegistration storage across the package rename.
• Nit: Update stale grammar references in STTService Javadoc.

Reviewed changes

Copilot reviewed 63 out of 63 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Reviewed change
itests/org.openhab.core.voice.tests/src/main/java/org/openhab/core/voice/voiceconsolecommandextension/VoicesCommandTest.java	Updates TTS stub imports.
itests/org.openhab.core.voice.tests/src/main/java/org/openhab/core/voice/voiceconsolecommandextension/SayCommandTest.java	Updates STT/TTS imports.
itests/org.openhab.core.voice.tests/src/main/java/org/openhab/core/voice/voiceconsolecommandextension/InterpretCommandTest.java	Updates text and TTS imports.
itests/org.openhab.core.voice.tests/src/main/java/org/openhab/core/voice/tts/VoiceStub.java	Moves the voice test stub package.
itests/org.openhab.core.voice.tests/src/main/java/org/openhab/core/voice/tts/TTSServiceStub.java	Moves the TTS test stub package.
itests/org.openhab.core.voice.tests/src/main/java/org/openhab/core/voice/text/HumanLanguageInterpreterStub.java	Moves the interpreter test stub package.
itests/org.openhab.core.voice.tests/src/main/java/org/openhab/core/voice/stt/STTServiceStub.java	Moves the STT stub and adopts the new API.
itests/org.openhab.core.voice.tests/src/main/java/org/openhab/core/voice/internal/VoiceManagerImplTest.java	Updates relocated service imports.
itests/org.openhab.core.voice.tests/src/main/java/org/openhab/core/voice/dialog/trigger/ks/KSServiceStub.java	Moves the keyword-spotting test stub.
bundles/org.openhab.core.voice/src/test/java/org/openhab/core/voice/tts/TTSExceptionTest.java	Moves the TTS exception test package.
bundles/org.openhab.core.voice/src/test/java/org/openhab/core/voice/stt/STTExceptionTest.java	Moves the STT exception test package.
bundles/org.openhab.core.voice/src/test/java/org/openhab/core/voice/stt/SpeechRecognitionEventTest.java	Moves the recognition event test package.
bundles/org.openhab.core.voice/src/test/java/org/openhab/core/voice/stt/SpeechRecognitionErrorEventTest.java	Moves the recognition error test package.
bundles/org.openhab.core.voice/src/test/java/org/openhab/core/voice/internal/tts/cache/TTSLRUCacheImplTest.java	Moves cache tests and updates imports.
bundles/org.openhab.core.voice/src/test/java/org/openhab/core/voice/internal/text/interpreter/StandardInterpreterTest.java	Updates STT/TTS imports.
bundles/org.openhab.core.voice/src/main/java/org/openhab/core/voice/VoiceManager.java	References relocated voice APIs.
bundles/org.openhab.core.voice/src/main/java/org/openhab/core/voice/tts/Voice.java	Moves the voice API.
bundles/org.openhab.core.voice/src/main/java/org/openhab/core/voice/tts/TTSService.java	Moves the TTS API.
bundles/org.openhab.core.voice/src/main/java/org/openhab/core/voice/tts/TTSException.java	Moves the TTS exception.
bundles/org.openhab.core.voice/src/main/java/org/openhab/core/voice/tts/TTSCache.java	Moves the TTS cache API.
bundles/org.openhab.core.voice/src/main/java/org/openhab/core/voice/tts/CachedTTSService.java	Moves the cached TTS API.
bundles/org.openhab.core.voice/src/main/java/org/openhab/core/voice/tts/AbstractCachedTTSService.java	Moves the cached TTS base implementation.
bundles/org.openhab.core.voice/src/main/java/org/openhab/core/voice/text/interpreter/llm/LLMItemSerializer.java	Makes the serializer a utility class.
bundles/org.openhab.core.voice/src/main/java/org/openhab/core/voice/text/HumanLanguageInterpreter.java	Updates dialog context references.
bundles/org.openhab.core.voice/src/main/java/org/openhab/core/voice/stt/STTServiceHandle.java	Moves the STT handle API.
bundles/org.openhab.core.voice/src/main/java/org/openhab/core/voice/stt/STTService.java	Moves and simplifies the STT API.
bundles/org.openhab.core.voice/src/main/java/org/openhab/core/voice/stt/STTListener.java	Moves the STT listener API.
bundles/org.openhab.core.voice/src/main/java/org/openhab/core/voice/stt/STTException.java	Moves the STT exception.
bundles/org.openhab.core.voice/src/main/java/org/openhab/core/voice/stt/STTEvent.java	Moves the STT event API.
bundles/org.openhab.core.voice/src/main/java/org/openhab/core/voice/stt/SpeechRecognitionEvent.java	Moves the recognition event.
bundles/org.openhab.core.voice/src/main/java/org/openhab/core/voice/stt/SpeechRecognitionErrorEvent.java	Moves the recognition error event.
bundles/org.openhab.core.voice/src/main/java/org/openhab/core/voice/stt/RecognitionStopEvent.java	Moves the recognition stop event.
bundles/org.openhab.core.voice/src/main/java/org/openhab/core/voice/stt/RecognitionStartEvent.java	Moves the recognition start event.
bundles/org.openhab.core.voice/src/main/java/org/openhab/core/voice/stt/AudioStopEvent.java	Moves the audio stop event.
bundles/org.openhab.core.voice/src/main/java/org/openhab/core/voice/stt/AudioStartEvent.java	Moves the audio start event.
bundles/org.openhab.core.voice/src/main/java/org/openhab/core/voice/internal/VoiceManagerImpl.java	Updates relocated APIs and STT calls.
bundles/org.openhab.core.voice/src/main/java/org/openhab/core/voice/internal/VoiceConsoleCommandExtension.java	Updates relocated API imports.
bundles/org.openhab.core.voice/src/main/java/org/openhab/core/voice/internal/tts/cache/TTSLRUCacheImpl.java	Moves the TTS cache implementation.
bundles/org.openhab.core.voice/src/main/java/org/openhab/core/voice/internal/tts/cache/AudioStreamFromCache.java	Moves cached stream support.
bundles/org.openhab.core.voice/src/main/java/org/openhab/core/voice/internal/tts/cache/AudioFormatInfo.java	Moves cached audio metadata.
bundles/org.openhab.core.voice/src/main/java/org/openhab/core/voice/internal/dialog/DialogProcessor.java	Moves dialog processing internals.
bundles/org.openhab.core.voice/src/main/java/org/openhab/core/voice/internal/AudioDialogProviderImpl.java	Updates dialog trigger imports.
bundles/org.openhab.core.voice/src/main/java/org/openhab/core/voice/dialog/trigger/ks/KSServiceHandle.java	Moves the keyword-spotting handle API.
bundles/org.openhab.core.voice/src/main/java/org/openhab/core/voice/dialog/trigger/ks/KSService.java	Moves the keyword-spotting service API.
bundles/org.openhab.core.voice/src/main/java/org/openhab/core/voice/dialog/trigger/ks/KSpottedEvent.java	Moves the spotted event.
bundles/org.openhab.core.voice/src/main/java/org/openhab/core/voice/dialog/trigger/ks/KSListener.java	Moves the keyword-spotting listener.
bundles/org.openhab.core.voice/src/main/java/org/openhab/core/voice/dialog/trigger/ks/KSException.java	Moves the keyword-spotting exception.
bundles/org.openhab.core.voice/src/main/java/org/openhab/core/voice/dialog/trigger/ks/KSEvent.java	Moves the keyword-spotting event API.
bundles/org.openhab.core.voice/src/main/java/org/openhab/core/voice/dialog/trigger/ks/KSErrorEvent.java	Moves the keyword-spotting error event.
bundles/org.openhab.core.voice/src/main/java/org/openhab/core/voice/dialog/trigger/DTTriggeredEvent.java	Moves the dialog trigger event.
bundles/org.openhab.core.voice/src/main/java/org/openhab/core/voice/dialog/trigger/DTServiceHandle.java	Moves the dialog trigger handle.
bundles/org.openhab.core.voice/src/main/java/org/openhab/core/voice/dialog/trigger/DTService.java	Moves the dialog trigger service API.
bundles/org.openhab.core.voice/src/main/java/org/openhab/core/voice/dialog/trigger/DTListener.java	Moves the dialog trigger listener.
bundles/org.openhab.core.voice/src/main/java/org/openhab/core/voice/dialog/trigger/DTException.java	Moves the dialog trigger exception.
bundles/org.openhab.core.voice/src/main/java/org/openhab/core/voice/dialog/trigger/DTEvent.java	Moves the dialog trigger event API.
bundles/org.openhab.core.voice/src/main/java/org/openhab/core/voice/dialog/trigger/DTErrorEvent.java	Moves the dialog trigger error event.
bundles/org.openhab.core.voice/src/main/java/org/openhab/core/voice/dialog/trigger/BasicDTService.java	Moves the basic trigger service API.
bundles/org.openhab.core.voice/src/main/java/org/openhab/core/voice/dialog/DialogRegistration.java	Moves the persisted dialog registration model.
bundles/org.openhab.core.voice/src/main/java/org/openhab/core/voice/dialog/DialogContext.java	Moves the dialog context model.
bundles/org.openhab.core.model.script/src/org/openhab/core/model/script/actions/Voice.java	Updates script voice API references.
bundles/org.openhab.core.io.rest.voice/src/main/java/org/openhab/core/io/rest/voice/internal/VoiceResource.java	Updates REST voice API imports.
bundles/org.openhab.core.io.rest.voice/src/main/java/org/openhab/core/io/rest/voice/internal/VoiceMapper.java	Updates voice mapping imports.
bundles/org.openhab.core.io.rest.voice/src/main/java/org/openhab/core/io/rest/voice/internal/VoiceDTO.java	Updates voice DTO imports.

Suppressed comments (3)

bundles/org.openhab.core.voice/src/main/java/org/openhab/core/voice/dialog/DialogRegistration.java:13

• Changing this class's package changes both the storage name from DialogRegistration.class.getName() in VoiceManagerImpl and the serialized entity type. On upgrade, JsonStorage will open a new org.openhab.core.voice.dialog.DialogRegistration.json instead of the existing org.openhab.core.voice.DialogRegistration.json, so persistent dialog registrations are lost (and retaining the old file still requires a type migration). Keep a stable storage key and add a migration/compatibility path for the old class name.
  bundles/org.openhab.core.voice/src/main/java/org/openhab/core/voice/stt/STTService.java:86
• The new three-argument signature no longer accepts grammars, but this method's Javadoc still says recognition uses the passed grammars and retains the JSGF @see. That documents an argument consumers cannot supply and can mislead STT providers; remove or update those stale references to match the new API.

This issue also appears on line 86 of the same file.
bundles/org.openhab.core.voice/src/main/java/org/openhab/core/voice/stt/STTService.java:86

• This is an additional breaking change beyond the package relocation: every third-party STTService implementation compiled against the previous interface must now change its recognize method because the grammars parameter was removed. Since the repository has no remaining in-tree callers, this can be easy to miss; retain a compatibility/deprecated bridge or explicitly handle this as a separate API migration.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[florian-h05]

@kaikreuzer Addressed Copilot review:

• Update Import-Package declarations for Voice actions.
• Added RenamingTypeMigrator to StorageService for DialogRegistration to rename inside JSONDB files.
• Added UpgradeTool job to rename JSONDB files for DialogRegistration relocation.

[wborn]

Looks like the description of the PR is missing as requested in the PR template:

---

Description

Please give a few sentences describing the overall goals of the pull request.
Give enough details to make the improvement and changes of the PR understandable
to both developers and tech-savy users.

Please keep the following in mind:

• What is the classification of the PR, e.g. Bugfix, Improvement, Novel Addition, ... ?
• Did you describe the PRs motivation and goal?
• Did you provide a link to any prior discussion, e.g. an issue or community forum thread?
• Did you describe new features for the end user?
• Did you describe any noteworthy changes in usage for the end user?
• Was the documentation updated accordingly, e.g. the Core README?
• Does your contribution follow the coding guidelines:
  https://www.openhab.org/docs/developer/guidelines.html
• Did you check for any (relevant) issues from the static code analysis?
• Did you sign-off your work:
  https://www.openhab.org/docs/developer/contributing.html#sign-your-work