Class SORIAudioRecognizer
-
- All Implemented Interfaces:
public class SORIAudioRecognizerThe primary entry point for the SORI SDK that handles audio recognition.
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description public interfaceSORIAudioRecognizer.NotificationProviderInterface for delegate an audio recognition service foreground notification. You can implement this interface to customize the notification.
public classSORIAudioRecognizer.HandleUrlExceptionpublic classSORIAudioRecognizer.Companion
-
Field Summary
Fields Modifier and Type Field Description public final static StringEXTRA_STOP_REASONpublic final static StringERROR_CAPTURE_RESUME_FAILEDpublic final static StringSTOP_REASON_USER_NOTIFICATION_ACTIONpublic final static StringEXTRA_NOTIFICATION_STOP_ACTION_TITLEpublic final static StringEXTRA_NOTIFICATION_STOP_ACTION_VISIBLEpublic final static StringEXTRA_NOTIFICATION_VISIBLE_CHANNELprivate final IMetadataProvidermetadataProviderprivate final ILocationProviderlocationProviderprivate final SORIAudioMarkerStateaudioMarkerStateprivate final SORIChannelStatechannelStateprivate final StringchannelStateReceivedAtUtcprivate final volatile StringlastStopReasonprivate final BooleanisRecognitionPausedpublic final static SORIAudioRecognizer.CompanionCompanion
-
Constructor Summary
Constructors Constructor Description SORIAudioRecognizer(String applicationId, String secretKey)
-
Method Summary
Modifier and Type Method Description final IMetadataProvidergetMetadataProvider()final ILocationProvidergetLocationProvider()final SORIAudioMarkerStategetAudioMarkerState()final SORIChannelStategetChannelState()final StringgetChannelStateReceivedAtUtc()final StringgetLastStopReason()Reason of the most recent STOPPED service state, or null for an ordinary stop (for example stopRecognition, a failure or a restart). final BooleanisRecognitionPaused()final UnitsetNotificationOptions(String stopActionTitle, Boolean stopActionVisible, Boolean visibleChannel)Optional foreground-service notification options for the next startRecognition or getServiceIntent. final UnitsetNotificationOptions(String stopActionTitle, Boolean stopActionVisible)Optional foreground-service notification options for the next startRecognition or getServiceIntent. final UnitsetNotificationOptions(String stopActionTitle)Optional foreground-service notification options for the next startRecognition or getServiceIntent. final UnitsetNotificationOptions()Optional foreground-service notification options for the next startRecognition or getServiceIntent. final UnitsetMetadataProvider(IMetadataProvider provider)Set the metadata provider for the SORI SDK. final UnitsetLocationProvider(ILocationProvider provider)Set the location provider for the SORI SDK. final UnitsetConfig(SORIConfig config)Sets the configuration: network handling, diagnostics and the recognition mode (SORIConfig.recognitionMode, SORIConfig.serverRecognition). final UnitsetListener(Context ctx, ISORIListener listener)Set the listener interface for SORI SDK events. final IntentgetServiceIntent(Context ctx, String title, String body, Integer icon)Creates an intent to start the SORI Audio Recognition Service. final UnitstartRecognition(Context ctx, String title, String body, Integer icon)Starts the SORI Audio Recognition Service. final SORIRecognitionControlResultpauseRecognition(Context ctx, String title, String body)Pauses recognition: the microphone is released ( AudioRecordstopped and released, so the system microphone indicator turns off) and no fingerprinting, marker scanning, matching or server query runs, while the foreground service and its notification stay.final SORIRecognitionControlResultpauseRecognition(Context ctx, String title)Pauses recognition: the microphone is released ( AudioRecordstopped and released, so the system microphone indicator turns off) and no fingerprinting, marker scanning, matching or server query runs, while the foreground service and its notification stay.final SORIRecognitionControlResultpauseRecognition(Context ctx)Pauses recognition: the microphone is released ( AudioRecordstopped and released, so the system microphone indicator turns off) and no fingerprinting, marker scanning, matching or server query runs, while the foreground service and its notification stay.final SORIRecognitionControlResultresumeRecognition(Context ctx)Resumes recognition paused by pauseRecognition: capture re-opens in the running foreground service (no new startForegroundService()call), the notification returns to its start-time text and icon, and ServiceState.STARTED is reported again.final UnitstopRecognition(Context ctx)Stops the SORI Audio Recognition Service. final Unitcleanup(Context ctx)Clean up resources including EventBus subscription and BroadcastReceiver. final UnitdetachClient(Context ctx)Detach a UI/engine client while keeping an explicitly started foreground service running. final UnitclearState(Context ctx)Clears the match state of the SORI Audio Recognition Service. final LonggetRemainingServiceTime()Gets the remaining service runtime in milliseconds before the Android 15 time limit. final BooleanisServiceApproachingTimeLimit()Checks if the service is approaching the Android 15 time limit. final UnithandleActionURL(Context ctx, URL url)Visits the actual action URL that retrieves from the API Server. final UnithandleActionURL(Context ctx, String url)Visits the actual action URL that retrieves from the API Server. final UnithandleActionURL(Context ctx, SORICampaign campaign)Visits the actual action URL that retrieves from the API Server. final UpdateResultupdateDatabase(Context ctx)Updates the audio recognition database by checking for and downloading new audiopacks. -
-
Method Detail
-
getMetadataProvider
final IMetadataProvider getMetadataProvider()
-
getLocationProvider
final ILocationProvider getLocationProvider()
-
getAudioMarkerState
final SORIAudioMarkerState getAudioMarkerState()
-
getChannelState
final SORIChannelState getChannelState()
-
getChannelStateReceivedAtUtc
final String getChannelStateReceivedAtUtc()
-
getLastStopReason
final String getLastStopReason()
Reason of the most recent STOPPED service state, or null for an ordinary stop (for example stopRecognition, a failure or a restart). It is STOP_REASON_USER_NOTIFICATION_ACTION when the user tapped the notification's stop action, which an app should treat as an explicit pause. It is updated before ISORIListener.onStateChanged is called with STOPPED, and cleared when recognition starts (STARTED, or PAUSED for a session that comes up paused).
-
isRecognitionPaused
final Boolean isRecognitionPaused()
-
setNotificationOptions
@JvmOverloads() final Unit setNotificationOptions(String stopActionTitle, Boolean stopActionVisible, Boolean visibleChannel)
Optional foreground-service notification options for the next startRecognition or getServiceIntent.
- Parameters:
stopActionTitle- label of the stop action; null or blank uses "Stop".stopActionVisible- false removes the stop action entirely.visibleChannel- true posts the notification to a separate, silent but visible IMPORTANCE_LOW channel (com.iplateia.sorisdk.v2, PRIORITY_LOW, shown in the status bar).
-
setNotificationOptions
@JvmOverloads() final Unit setNotificationOptions(String stopActionTitle, Boolean stopActionVisible)
Optional foreground-service notification options for the next startRecognition or getServiceIntent.
- Parameters:
stopActionTitle- label of the stop action; null or blank uses "Stop".stopActionVisible- false removes the stop action entirely.
-
setNotificationOptions
@JvmOverloads() final Unit setNotificationOptions(String stopActionTitle)
Optional foreground-service notification options for the next startRecognition or getServiceIntent.
- Parameters:
stopActionTitle- label of the stop action; null or blank uses "Stop".
-
setNotificationOptions
@JvmOverloads() final Unit setNotificationOptions()
Optional foreground-service notification options for the next startRecognition or getServiceIntent.
-
setMetadataProvider
final Unit setMetadataProvider(IMetadataProvider provider)
Set the metadata provider for the SORI SDK.
Server recognition queries carry the provider's map as caller metadata. It is read once when a query window is frozen (on the capture thread, so keep IMetadataProvider.getMetadata fast and thread-safe) and sent unchanged however long the window is held for its delay, so the webhook sees the state in effect when the audio was captured. A changed map (or a new provider) applies to the next frozen window without restarting recognition.
-
setLocationProvider
final Unit setLocationProvider(ILocationProvider provider)
Set the location provider for the SORI SDK.
-
setConfig
final Unit setConfig(SORIConfig config)
Sets the configuration: network handling, diagnostics and the recognition mode (SORIConfig.recognitionMode, SORIConfig.serverRecognition). The configuration is validated when it is constructed.
Without an active session the configuration is used by the next startRecognition.
On an active session (starting, running or paused):
Same SORIConfig.recognitionMode and SORIConfig.serverRecognition as the running configuration: applied at once, as in 5.1.2 (network handling, diagnostics, and an SORIConfig.audiomarker change restarts capture). An on-device application therefore sees no change in behaviour.
Another mode or other server options: the whole configuration is held and takes effect at the next startRecognition or resumeRecognition call, not when it is set. That call applies it as follows:
Only the server tuning differs (interval, burst or delay of SORIConfig.serverRecognition, same mode, nothing else changed): applied in place, on the same recorder and capture generation, without restarting the service. The new period applies from the next tick of the running capture grid.
Anything else differs (for example the recognition mode): applied as a configuration change, which restarts the session for a new mode. If the restarted session cannot run (for example a server mode below Android 10), it stops and reports the reason through ISORIListener.onError and the STOPPED state, as a start with that configuration would.
The last configuration set wins: a later configuration whose server part equals the running one is applied at once and drops a held one. A held configuration also becomes the process-wide one (network recovery, the pending-request queue) only when it takes effect. A recognizer that binds to a running service hands over its configuration under the same rule.
As in 5.1.2, only a bound recognizer changes the running service's configuration at once. A recognizer that is not bound (for example after detachClient) reaches the recognition service in this process only to hold a server-part change, which the next start or resume applies.
Never throws and may be called from any thread; a call from another thread waits briefly for the service's main thread.
- Parameters:
config- The configuration
-
setListener
final Unit setListener(Context ctx, ISORIListener listener)
Set the listener interface for SORI SDK events. It helps to subscribe to the useful events like campaign found, service state changes, etc.
- Parameters:
ctx- The context from which the service is started.listener- The listener for SORI SDK events.
-
getServiceIntent
final Intent getServiceIntent(Context ctx, String title, String body, Integer icon)
Creates an intent to start the SORI Audio Recognition Service. This intent can be used to start the service from an activity or another component. example usage:
val intent = SORIAudioRecognizer.getServiceIntent(this) this.startForegroundService(intent)- Parameters:
ctx- The context from which the service is started.title- The title of the notification.body- The body of the notification.icon- The icon resource ID for the notification.- Returns:
An intent to start the SORI Audio Recognition Service.
-
startRecognition
final Unit startRecognition(Context ctx, String title, String body, Integer icon)
Starts the SORI Audio Recognition Service. Repeated calls while a start is pending or recognition is active do not start anything and keep the notification, listener and capture session, including across instances. They apply a configuration that setConfig set while the session was active (see setConfig); with no such change the call is a no-op. Use setListener to attach a listener.
While recognition is paused (pauseRecognition) this call is a resumeRecognition: the service is already in the foreground, so no new
startForegroundService()call is made, and a pending configuration is applied. Non-null title, body and icon then replace the notification's retained text and icon; null arguments keep them. example usage:val recognizer = SORIAudioRecognizer("your_application_id", "your_secret_key") recognizer.startRecognition(this)- Parameters:
ctx- The context from which the service is started.title- The title of the foreground notification.body- The body of the foreground notification.icon- The icon resource ID for the foreground notification.
-
pauseRecognition
@JvmOverloads() final SORIRecognitionControlResult pauseRecognition(Context ctx, String title, String body)
Pauses recognition: the microphone is released (
AudioRecordstopped and released, so the system microphone indicator turns off) and no fingerprinting, marker scanning, matching or server query runs, while the foreground service and its notification stay. Use it to save battery when the app knows recognition is not needed; resumeRecognition re-opens capture inside the same service, also from the background, where startRecognition after a stopRecognition would not be allowed.Running: pauses and reports ServiceState.PAUSED through ISORIListener.onStateChanged.
Already paused: SORIRecognitionControlResult.ALREADY_IN_STATE, no second event; non-blank text still updates the notification.
Start pending: accepted; recognition comes up paused without opening the microphone (PAUSED instead of STARTED). A stopRecognition discards it.
Not started or stopped: SORIRecognitionControlResult.NOT_RUNNING; the service is never started.
title and body are shown in the notification while paused; null or blank keeps the value currently shown. They never replace the start-time text, which a resume restores exactly, and notificationProvider still receives every rebuilt notification.
The SDK holds no wake lock, and none while paused: nothing in the SDK keeps the CPU awake. An app that wants a timed resume with the screen off must schedule it with
AlarmManager(or hold its own wake lock), not with a plain in-process timer.Never throws. The call reaches the recognition service in this process directly, so it works after detachClient and from any thread; the capture itself is released on the main thread.
-
pauseRecognition
@JvmOverloads() final SORIRecognitionControlResult pauseRecognition(Context ctx, String title)
Pauses recognition: the microphone is released (
AudioRecordstopped and released, so the system microphone indicator turns off) and no fingerprinting, marker scanning, matching or server query runs, while the foreground service and its notification stay. Use it to save battery when the app knows recognition is not needed; resumeRecognition re-opens capture inside the same service, also from the background, where startRecognition after a stopRecognition would not be allowed.Running: pauses and reports ServiceState.PAUSED through ISORIListener.onStateChanged.
Already paused: SORIRecognitionControlResult.ALREADY_IN_STATE, no second event; non-blank text still updates the notification.
Start pending: accepted; recognition comes up paused without opening the microphone (PAUSED instead of STARTED). A stopRecognition discards it.
Not started or stopped: SORIRecognitionControlResult.NOT_RUNNING; the service is never started.
title and body are shown in the notification while paused; null or blank keeps the value currently shown. They never replace the start-time text, which a resume restores exactly, and notificationProvider still receives every rebuilt notification.
The SDK holds no wake lock, and none while paused: nothing in the SDK keeps the CPU awake. An app that wants a timed resume with the screen off must schedule it with
AlarmManager(or hold its own wake lock), not with a plain in-process timer.Never throws. The call reaches the recognition service in this process directly, so it works after detachClient and from any thread; the capture itself is released on the main thread.
-
pauseRecognition
@JvmOverloads() final SORIRecognitionControlResult pauseRecognition(Context ctx)
Pauses recognition: the microphone is released (
AudioRecordstopped and released, so the system microphone indicator turns off) and no fingerprinting, marker scanning, matching or server query runs, while the foreground service and its notification stay. Use it to save battery when the app knows recognition is not needed; resumeRecognition re-opens capture inside the same service, also from the background, where startRecognition after a stopRecognition would not be allowed.Running: pauses and reports ServiceState.PAUSED through ISORIListener.onStateChanged.
Already paused: SORIRecognitionControlResult.ALREADY_IN_STATE, no second event; non-blank text still updates the notification.
Start pending: accepted; recognition comes up paused without opening the microphone (PAUSED instead of STARTED). A stopRecognition discards it.
Not started or stopped: SORIRecognitionControlResult.NOT_RUNNING; the service is never started.
title and body are shown in the notification while paused; null or blank keeps the value currently shown. They never replace the start-time text, which a resume restores exactly, and notificationProvider still receives every rebuilt notification.
The SDK holds no wake lock, and none while paused: nothing in the SDK keeps the CPU awake. An app that wants a timed resume with the screen off must schedule it with
AlarmManager(or hold its own wake lock), not with a plain in-process timer.Never throws. The call reaches the recognition service in this process directly, so it works after detachClient and from any thread; the capture itself is released on the main thread.
-
resumeRecognition
final SORIRecognitionControlResult resumeRecognition(Context ctx)
Resumes recognition paused by pauseRecognition: capture re-opens in the running foreground service (no new
startForegroundService()call), the notification returns to its start-time text and icon, and ServiceState.STARTED is reported again. Resuming takes as long as opening the microphone and, like any capture start, the first recognition needs a full query window of new audio. A resume is a capture discontinuity: no local fingerprint window, marker window or server query spans the pause, while the server query cadence (SORIConfig.serverRecognition) stays configured.A configuration set with setConfig while the session was active takes effect with this call, also when the session is running rather than paused (the result is then SORIRecognitionControlResult.ALREADY_IN_STATE); see setConfig.
Paused: SORIRecognitionControlResult.APPLIED. If the microphone cannot be re-opened (permission revoked, held by another app, refused by the platform) recognition stays paused and the failure is reported through ISORIListener.onError (
capture_resume_failed) with a repeated PAUSED state.Not started or stopped: SORIRecognitionControlResult.NOT_RUNNING. This never starts the service; call startRecognition for that.
Never throws; works after detachClient and from any thread.
-
stopRecognition
final Unit stopRecognition(Context ctx)
Stops the SORI Audio Recognition Service. A paused session stops the same way and reports the usual STOPPED state; the pause (and one accepted while the start is pending) is discarded. example usage:
recognizer.stopRecognition(this)- Parameters:
ctx- The context from which the service is stopped.
-
cleanup
final Unit cleanup(Context ctx)
Clean up resources including EventBus subscription and BroadcastReceiver. This should be called when completely done with the recognizer.
- Parameters:
ctx- The context used for unregistering receivers
-
detachClient
final Unit detachClient(Context ctx)
Detach a UI/engine client while keeping an explicitly started foreground service running.
-
clearState
final Unit clearState(Context ctx)
Clears the match state of the SORI Audio Recognition Service. This method is useful to reset the state of the service. example usage:
recognizer.clearState(this)- Parameters:
ctx- The context from which the service is cleared.
-
getRemainingServiceTime
final Long getRemainingServiceTime()
Gets the remaining service runtime in milliseconds before the Android 15 time limit. Returns -1 if there's no time limit (pre-Android 15), if the service is not running, or if the service is not bound.
- Returns:
The remaining time in milliseconds, or -1 if not applicable
-
isServiceApproachingTimeLimit
final Boolean isServiceApproachingTimeLimit()
Checks if the service is approaching the Android 15 time limit. Returns true if less than 5 minutes remain before the time limit. Returns false if the service is not running, not bound, or on pre-Android 15 devices.
- Returns:
true if approaching time limit, false otherwise
-
handleActionURL
final Unit handleActionURL(Context ctx, URL url)
Visits the actual action URL that retrieves from the API Server.
Although default browser in user's device can handle it automatically but, doing this manually can be helpful on the reasons below:
The bounce URL does not shown to the user. (preventing flashing)
Application can handle their own schema handler.
Seamlessly track user activities without annoying.
- Parameters:
ctx- The context from which the service is started.url- The action URL from SORICampaign.
-
handleActionURL
final Unit handleActionURL(Context ctx, String url)
Visits the actual action URL that retrieves from the API Server.
Although default browser in user's device can handle it automatically but, doing this manually can be helpful on the reasons below:
The bounce URL does not shown to the user. (preventing flashing)
Application can handle their own schema handler.
Seamlessly track user activities without annoying.
- Parameters:
ctx- The context from which the service is started.url- The action URL from SORICampaign.
-
handleActionURL
final Unit handleActionURL(Context ctx, SORICampaign campaign)
Visits the actual action URL that retrieves from the API Server.
Although default browser in user's device can handle it automatically but, doing this manually can be helpful on the reasons below:
The bounce URL does not shown to the user. (preventing flashing)
Application can handle their own schema handler.
Seamlessly track user activities without annoying.
- Parameters:
ctx- The context from which the service is started.campaign- The SORICampaign object that contains the action URL.
-
updateDatabase
final UpdateResult updateDatabase(Context ctx)
Updates the audio recognition database by checking for and downloading new audiopacks. This method can be called independently of the startRecognition method.
The method performs the following steps:
Authenticates with the SORI API
Checks if a database update is available
Downloads the new audiopack if available
Applies the update immediately if the recognition service is running
Stores the update for later application if the service is not running
example usage:
val recognizer = SORIAudioRecognizer("your_application_id", "your_secret_key") CoroutineScope(Dispatchers.Main).launch { val result = recognizer.updateDatabase(this@MainActivity) if (result.success) { if (result.updateAvailable) { Log.d("SORI", "Database updated to version: ${result.currentVersion}") } else { Log.d("SORI", "Database is already up to date") } } else { Log.e("SORI", "Database update failed: ${result.errorMessage}") } }- Parameters:
ctx- The context from which the update is requested.- Returns:
The validation/cache result. A bound running service receives the candidate between queries; otherwise it is loaded on the next start. This does not start recognition.
-
-
-
-