diff --git a/differences.md b/differences.md index 813bf26c5..12934e7d5 100644 --- a/differences.md +++ b/differences.md @@ -190,7 +190,15 @@ TalkBack ignored the order for a row whose checkbox or switch has no text of its ### "Backtalk off" at the right volume -When you turn Backtalk off, it says "Backtalk off" at the accessibility volume, using your device's real volume levels. TalkBack only approximated that volume. +When you turn Backtalk off, it says "Backtalk off" at the accessibility volume, using your device's real volume levels. This includes Samsung phones, and stays right when you connect or disconnect headphones while Backtalk is on. On Bluetooth headphones that control their own volume, it can be one volume step louder or quieter, about 3 dB, because those headphones can set the media volume between steps and Android doesn't tell apps where. TalkBack only approximated that volume. + +### Volume said as it changes + +When you press a volume key, Backtalk says the new volume right away and stops what it was saying. During continuous reading it waits for the current item to finish instead, so reading goes on. A newer level replaces one that hasn't finished. The first change names the volume, such as "Music volume set to 50 percent", and changes to the same volume less than 2 seconds apart say only the percentage. If you hold the key down, Backtalk says the first level, stays quiet while the volume keeps changing, and says the level you end at when you let go. When media is muted or unmuted, Backtalk says so the same way. TalkBack waited until the keys had been still for 2 seconds, and after the first press it waited 4 seconds. Backtalk also says the media volume while media plays, where TalkBack said it only when nothing was playing. + +Each output, such as the phone speaker or a pair of headphones, keeps its own media, call, notification and accessibility volumes, and Android switches to them when audio moves there. Backtalk doesn't say a change of one of these volumes that comes with a new output unless a volume key made it, so connecting or disconnecting headphones stays quiet. Headphones can report the same level again a moment later, and Backtalk doesn't say one of these levels that hasn't changed unless a volume key reported it. TalkBack said the level headphones set. If the new output's level is the one you already had, nothing changes, so the first press on the headphones' own controls after that isn't said. + +When you change the volume with a slider, Backtalk says only the slider's value. To stop hearing the volume, including mute, turn off **Verbosity** > **Speak volume changes**. ### Table column headers diff --git a/talkback/src/main/java/com/google/android/accessibility/talkback/FinalAnnouncementVolume.kt b/talkback/src/main/java/com/google/android/accessibility/talkback/FinalAnnouncementVolume.kt index 299f35ef1..7ebf30d34 100644 --- a/talkback/src/main/java/com/google/android/accessibility/talkback/FinalAnnouncementVolume.kt +++ b/talkback/src/main/java/com/google/android/accessibility/talkback/FinalAnnouncementVolume.kt @@ -20,17 +20,19 @@ import android.media.AudioAttributes import android.media.AudioDeviceInfo import android.media.AudioManager import android.os.Build +import com.google.android.accessibility.talkback.audio.outputsFor import kotlin.math.pow /** * Works out how loud to speak "Backtalk off". * - * Android shuts the accessibility audio stream down before Backtalk speaks that last announcement, - * so it plays at the media volume. To keep it at the accessibility volume, the speech is made - * quieter by the difference between the two. Android 9 and later report each volume step's real - * loudness in decibels for the current output, which is exact. Before that, the difference is - * guessed from where the two volume sliders are, which lowers the speech too little at the - * quietest accessibility volumes, where Android's volume steps are furthest apart. + * Android turns the accessibility volume up to the media volume's step before Backtalk speaks that + * last announcement. To keep it at the accessibility volume, the speech is made quieter by the + * difference between the two steps. Android 9 and later report each step's real loudness for the + * current output, which is exact. The accessibility stream's own loudness is used for both, + * because the media stream's can differ from it. Before Android 9, the difference is guessed from + * where the two volume sliders are, which lowers the speech too little at the quietest + * accessibility volumes, where Android's volume steps are furthest apart. */ object FinalAnnouncementVolume { /** @@ -59,7 +61,7 @@ object FinalAnnouncementVolume { return 0f } val gain = - decibelGain(audioManager, accessibilityIndex, musicIndex) + reportedGain(audioManager, accessibilityIndex, accessibilityMaxIndex, musicIndex, musicMaxIndex) ?: sliderGain( accessibilityIndex.toFloat() / accessibilityMaxIndex, musicIndex.toFloat() / musicMaxIndex, @@ -67,6 +69,43 @@ object FinalAnnouncementVolume { return speechVolume * gain } + /** + * The accessibility step that Android sets for media step [musicIndex], the way it matches the + * steps of two streams: in tenths of a step, from each stream's lowest step to its highest, then + * rounded. Bluetooth headphones can set the media volume between steps, which apps can't see, + * so there this can be a step off. + */ + @JvmStatic + fun accessibilityStepAtMediaVolume( + musicIndex: Int, + musicMinIndex: Int, + musicMaxIndex: Int, + accessibilityMinIndex: Int, + accessibilityMaxIndex: Int, + ): Int { + val musicRange = (musicMaxIndex - musicMinIndex) * 10 + val accessibilityRange = (accessibilityMaxIndex - accessibilityMinIndex) * 10 + val tenths = + accessibilityMinIndex * 10 + + ((musicIndex - musicMinIndex) * 10 * accessibilityRange + musicRange / 2) / musicRange + return (tenths + 5) / 10 + } + + /** + * The gain that turns a sound at the media step into one at the accessibility step, from 0 to 1, + * from the loudness Android reports for each. That is usually in decibels, which are at most + * 0 at full volume, but Samsung phones report a fraction of full loudness instead, from 0 to 1. + * Their fractions are above 0 at every step but the lowest, which is never asked for, so two + * values above 0 are fractions. + */ + @JvmStatic + fun gainFromReportedVolumes(accessibility: Float, music: Float): Float { + if (accessibility > 0f && music > 0f) { + return (accessibility / music).coerceIn(0f, 1f) + } + return gainFromDecibels(accessibility, music) + } + /** The gain that turns a sound at [musicDb] into one at [accessibilityDb], from 0 to 1. */ @JvmStatic fun gainFromDecibels(accessibilityDb: Float, musicDb: Float): Float { @@ -88,23 +127,37 @@ object FinalAnnouncementVolume { return 10f.pow((accessibilityFraction - musicFraction) / 0.4f) } - private fun decibelGain( + /** + * The gain from the accessibility stream's loudness at [accessibilityIndex] and at the step + * Android sets it to for media step [musicIndex]. + */ + private fun reportedGain( audioManager: AudioManager, accessibilityIndex: Int, + accessibilityMaxIndex: Int, musicIndex: Int, + musicMaxIndex: Int, ): Float? { if (Build.VERSION.SDK_INT < Build.VERSION_CODES.P) { return null } + val mediaStep = + accessibilityStepAtMediaVolume( + musicIndex, + audioManager.getStreamMinVolume(AudioManager.STREAM_MUSIC), + musicMaxIndex, + audioManager.getStreamMinVolume(AudioManager.STREAM_ACCESSIBILITY), + accessibilityMaxIndex, + ) val deviceType = outputDeviceType(audioManager) return try { - gainFromDecibels( + gainFromReportedVolumes( audioManager.getStreamVolumeDb( AudioManager.STREAM_ACCESSIBILITY, accessibilityIndex, deviceType, ), - audioManager.getStreamVolumeDb(AudioManager.STREAM_MUSIC, musicIndex, deviceType), + audioManager.getStreamVolumeDb(AudioManager.STREAM_ACCESSIBILITY, mediaStep, deviceType), ) } catch (e: IllegalArgumentException) { null @@ -119,7 +172,7 @@ object FinalAnnouncementVolume { .setUsage(AudioAttributes.USAGE_MEDIA) .setContentType(AudioAttributes.CONTENT_TYPE_SPEECH) .build() - audioManager.getAudioDevicesForAttributes(attributes).firstOrNull()?.let { + audioManager.outputsFor(attributes)?.firstOrNull()?.let { return it.type } } diff --git a/talkback/src/main/java/com/google/android/accessibility/talkback/TalkBackService.java b/talkback/src/main/java/com/google/android/accessibility/talkback/TalkBackService.java index 8220d4ef1..156e38baf 100644 --- a/talkback/src/main/java/com/google/android/accessibility/talkback/TalkBackService.java +++ b/talkback/src/main/java/com/google/android/accessibility/talkback/TalkBackService.java @@ -1427,6 +1427,12 @@ protected boolean onKeyEventInternal(KeyEvent keyEvent) { if (adjustSliderWithVolumeKey(keyEvent, triggerModifierPressed)) { return true; } + // Backtalk: a held volume key is said once, when it's released. This follows the keys that + // Backtalk routes to its own volume too, so the release is seen even if routing changes. + if (volumeMonitor != null + && (keyCode == KeyEvent.KEYCODE_VOLUME_DOWN || keyCode == KeyEvent.KEYCODE_VOLUME_UP)) { + volumeMonitor.onVolumeKeyEvent(keyEvent); + } if (keyAction == KeyEvent.ACTION_DOWN) { boolean handleVolumeKeyInTalkBack = isTouchInteracting @@ -2578,6 +2584,15 @@ public long getSpeechCacheWindowCounts() { focuser.setMenuManager(menuManager); volumeMonitor = new VolumeMonitor(pipeline.getFeedbackReturner(), this, callStateMonitor); + // Backtalk: a focused slider that the user just moved says its own value, and continuous + // reading must not be cut off. A change from elsewhere, such as headphones, is still said. + volumeMonitor.setSliderFocused( + () -> + RecentUserInput.isRecent() + && Role.getRole(accessibilityFocusMonitor.getSupportedAdjustableNode()) + == Role.ROLE_SEEK_CONTROL); + volumeMonitor.setContinuousReading( + () -> pipeline.getActorState().getContinuousRead().isActive()); selectorController = new SelectorController( this, @@ -3195,6 +3210,7 @@ private void resumeInfrastructure() { if (volumeMonitor != null) { ContextCompat.registerReceiver( this, volumeMonitor, volumeMonitor.getFilter(), RECEIVER_EXPORTED); + volumeMonitor.startAnnouncing(); if (FeatureSupport.hasAccessibilityAudioStream(this)) { // Cache the initial volume in case that the volume is never changed during runtime. volumeMonitor.cacheAccessibilityStreamVolume(); @@ -3347,6 +3363,7 @@ private void suspendInfrastructure() { if (volumeMonitor != null) { volumeMonitor.releaseControl(); volumeMonitor.clearVolumeChangedListener(); + volumeMonitor.stopAnnouncing(); } if (headphoneStateMonitor != null) { diff --git a/talkback/src/main/java/com/google/android/accessibility/talkback/audio/AudioDeviceRouter.kt b/talkback/src/main/java/com/google/android/accessibility/talkback/audio/AudioDeviceRouter.kt index 69750739c..d189639ce 100644 --- a/talkback/src/main/java/com/google/android/accessibility/talkback/audio/AudioDeviceRouter.kt +++ b/talkback/src/main/java/com/google/android/accessibility/talkback/audio/AudioDeviceRouter.kt @@ -308,21 +308,11 @@ class AudioDeviceRouter @JvmOverloads constructor( /** Whether [device] is Bluetooth and Android plays media on it. */ private fun playsAsMedia(am: AudioManager, device: AudioDeviceInfo): Boolean { if (Build.VERSION.SDK_INT < Build.VERSION_CODES.S) return false + // Where media plays now. The communication route doesn't change it. Android 12 can't say, so + // any connected Bluetooth media output counts. val media = - try { - if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) { - // Where media plays now. The communication route doesn't change it. - am.getAudioDevicesForAttributes( - AudioAttributes.Builder().setUsage(AudioAttributes.USAGE_MEDIA).build() - ) - } else { - // Android 12 can't say, so any connected Bluetooth media output counts. - am.getDevices(AudioManager.GET_DEVICES_OUTPUTS).toList() - } - } catch (e: Exception) { - Log.w(TAG, "Couldn't find where media plays", e) - return false - } + am.outputsFor(AudioAttributes.Builder().setUsage(AudioAttributes.USAGE_MEDIA).build()) + ?: return false return playsAsMedia(endpointOf(device), media.map(::endpointOf)) } @@ -398,20 +388,15 @@ class AudioDeviceRouter @JvmOverloads constructor( */ private fun accessibilityAudioGoesToTarget(am: AudioManager, targetDevice: AudioDeviceInfo): Boolean { if (Build.VERSION.SDK_INT < Build.VERSION_CODES.TIRAMISU) return true - return try { - val attrs = - AudioAttributes.Builder() - .setUsage(AudioAttributes.USAGE_ASSISTANCE_ACCESSIBILITY) - .setContentType(AudioAttributes.CONTENT_TYPE_SPEECH) - .build() - val devices = am.getAudioDevicesForAttributes(attrs) - if (devices.isEmpty()) return true - val onSpeaker = devices.any { it.type == AudioDeviceInfo.TYPE_BUILTIN_SPEAKER } - if (targetDevice.type == AudioDeviceInfo.TYPE_BUILTIN_SPEAKER) onSpeaker else !onSpeaker - } catch (e: Exception) { - Log.w(TAG, "getAudioDevicesForAttributes failed", e) - true - } + val attrs = + AudioAttributes.Builder() + .setUsage(AudioAttributes.USAGE_ASSISTANCE_ACCESSIBILITY) + .setContentType(AudioAttributes.CONTENT_TYPE_SPEECH) + .build() + val devices = am.outputsFor(attrs) + if (devices.isNullOrEmpty()) return true + val onSpeaker = devices.any { it.type == AudioDeviceInfo.TYPE_BUILTIN_SPEAKER } + return if (targetDevice.type == AudioDeviceInfo.TYPE_BUILTIN_SPEAKER) onSpeaker else !onSpeaker } /** diff --git a/talkback/src/main/java/com/google/android/accessibility/talkback/audio/AudioOutputs.kt b/talkback/src/main/java/com/google/android/accessibility/talkback/audio/AudioOutputs.kt new file mode 100644 index 000000000..1cb1824b4 --- /dev/null +++ b/talkback/src/main/java/com/google/android/accessibility/talkback/audio/AudioOutputs.kt @@ -0,0 +1,42 @@ +/* + * Copyright 2026 Backtalk contributors + * + * Licensed under the Apache License, Version 2.0 (the "License"); you may not + * use this file except in compliance with the License. You may obtain a copy of + * the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + * License for the specific language governing permissions and limitations under + * the License. + */ + +package com.google.android.accessibility.talkback.audio + +import android.media.AudioAttributes +import android.media.AudioDeviceInfo +import android.media.AudioManager +import android.os.Build +import android.util.Log + +/** + * The devices audio with [attributes] plays on, or null when Android can't say. Before Android 13 + * apps can't ask, so the connected outputs stand in for them. + */ +fun AudioManager.outputsFor(attributes: AudioAttributes): List? = + try { + if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) { + getAudioDevicesForAttributes(attributes) + } else { + getDevices(AudioManager.GET_DEVICES_OUTPUTS).toList() + } + } catch (e: RuntimeException) { + // Some phones throw here. + Log.w(TAG, "Could not find where audio plays", e) + null + } + +private const val TAG = "AudioOutputs" diff --git a/talkback/src/main/java/com/google/android/accessibility/talkback/gesture/GestureController.java b/talkback/src/main/java/com/google/android/accessibility/talkback/gesture/GestureController.java index 0a0a92556..1d2cf16e1 100644 --- a/talkback/src/main/java/com/google/android/accessibility/talkback/gesture/GestureController.java +++ b/talkback/src/main/java/com/google/android/accessibility/talkback/gesture/GestureController.java @@ -1043,6 +1043,12 @@ private void speak(String text) { private final VolumeChangedListener a11yVolumeChangedListener = new VolumeChangedListener() { + // Backtalk: this listener says the new accessibility volume, so VolumeMonitor doesn't. + @Override + public boolean announcesVolume(int type) { + return type == AudioManager.STREAM_ACCESSIBILITY; + } + @Override public void onVolumeChanged(int type, int value, int prevValue, int percent) { if (type != AudioManager.STREAM_ACCESSIBILITY) { diff --git a/talkback/src/main/java/com/google/android/accessibility/talkback/monitor/VolumeAnnouncer.kt b/talkback/src/main/java/com/google/android/accessibility/talkback/monitor/VolumeAnnouncer.kt new file mode 100644 index 000000000..e95776b1c --- /dev/null +++ b/talkback/src/main/java/com/google/android/accessibility/talkback/monitor/VolumeAnnouncer.kt @@ -0,0 +1,301 @@ +/* + * Copyright 2026 Backtalk contributors + * + * Licensed under the Apache License, Version 2.0 (the "License"); you may not + * use this file except in compliance with the License. You may obtain a copy of + * the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + * License for the specific language governing permissions and limitations under + * the License. + */ + +package com.google.android.accessibility.talkback.monitor + +import android.content.BroadcastReceiver +import android.content.Context +import android.content.Intent +import android.content.IntentFilter +import android.media.AudioAttributes +import android.media.AudioManager +import android.os.Handler +import android.os.Looper +import android.os.SystemClock +import android.view.KeyEvent +import androidx.core.content.ContextCompat +import com.google.android.accessibility.talkback.Feedback +import com.google.android.accessibility.talkback.Pipeline.FeedbackReturner +import com.google.android.accessibility.talkback.R +import com.google.android.accessibility.talkback.audio.outputsFor +import com.google.android.accessibility.utils.Performance.EVENT_ID_UNTRACKED +import com.google.android.accessibility.utils.compat.media.AudioManagerCompatUtils +import com.google.android.accessibility.utils.output.FeedbackItem +import com.google.android.accessibility.utils.output.SpeechController +import java.util.function.BooleanSupplier + +/** + * Says the new volume as soon as it changes, for [VolumeMonitor], and interrupts other speech, + * except during continuous reading, which an interruption would stop. TalkBack waited until the + * keys had been still for 2 seconds, and 2 seconds more after the first press. Each new level + * replaces the one before it, if that one hasn't finished. Media is said while it plays too, where + * TalkBack said it only when nothing played. + */ +class VolumeAnnouncer( + private val context: Context, + private val pipeline: FeedbackReturner, + private val callStateMonitor: CallStateMonitor?, + private val monitor: VolumeMonitor, +) { + private val audioManager = context.getSystemService(AudioManager::class.java) + private val handler = Handler(Looper.getMainLooper()) + + /** Whether a volume key is held, so that its repeated changes are kept quiet. */ + private var volumeKeyHeld = false + + /** The change held back while a volume key was held, said when the key is released. */ + private var heldChange: HeldChange? = null + + /** The stream that changed last, and when, to keep runs of changes short. */ + private var lastChangedStream = -1 + private var lastChangeTime = 0L + + /** When a volume key last went down, including the repeats of a held key. */ + private var lastVolumeKeyDownTime = -KEY_CHANGE_WINDOW_MS + + /** + * Each of [PER_OUTPUT_STREAMS] at its last change, to tell when an output brings its own level and + * when a level only repeats. + */ + private val lastLevels = mutableMapOf() + + /** + * Keeps the accessibility volume of the output in use, which Backtalk needs when it turns off. + * Each output has its own, and Android says when the accessibility stream moves to another one, + * after the move, where a device callback comes before it. + */ + private val outputReceiver = + object : BroadcastReceiver() { + override fun onReceive(context: Context, intent: Intent) { + val streamType = intent.getIntExtra(AudioManagerCompatUtils.EXTRA_VOLUME_STREAM_TYPE, -1) + if (streamType == AudioManager.STREAM_ACCESSIBILITY) monitor.cacheAccessibilityStreamVolume() + } + } + + /** Whether accessibility focus is on a slider, which says its own value. */ + var sliderFocused = BooleanSupplier { false } + + /** Whether continuous reading is on, which an interruption would stop. */ + var continuousReading = BooleanSupplier { false } + + private val announceAfterHold = Runnable { + val change = heldChange + forgetHold() + if (change != null) announceVolumeNow(change.streamType, change.brief) + } + + /** Starts following outputs and the levels they bring. */ + fun start() { + for (stream in PER_OUTPUT_STREAMS) { + lastLevels[stream] = StreamLevel(outputOf(stream), audioManager.getStreamVolume(stream)) + } + ContextCompat.registerReceiver( + context, + outputReceiver, + IntentFilter(AudioManagerCompatUtils.STREAM_DEVICES_CHANGED_ACTION), + ContextCompat.RECEIVER_NOT_EXPORTED, + ) + } + + /** Stops following outputs, and drops a held key's volume still to be said. */ + fun stop() { + context.unregisterReceiver(outputReceiver) + lastLevels.clear() + forgetHold() + } + + /** + * Whether a change of [streamType] to [volume] isn't the user's, so it's ignored: the level of + * another output, such as headphones that connect. Each output keeps its own level of the + * [PER_OUTPUT_STREAMS], so a change of one of them that comes with a new output and that no volume + * key made is the output's. Android can report that change before it says the device connected, + * so the output is looked up when the change comes. Headphones can then report the same level + * again, which isn't a change either. + */ + fun isIgnoredChange(streamType: Int, volume: Int): Boolean { + if (streamType !in PER_OUTPUT_STREAMS) return false + val last = lastLevels[streamType] + val byKey = changedByVolumeKey() + // A held key repeats many times a second, so the output isn't asked for each repeat. + val output = if (byKey && volumeKeyHeld) last?.output else outputOf(streamType) + lastLevels[streamType] = StreamLevel(output, volume) + if (byKey) return false + // Where the stream played isn't known before start or when Android couldn't say. + val newOutput = last?.output != null && output != null && output != last.output + return newOutput || volume == last?.volume + } + + /** + * Says a volume change right away, unless a listener says it ([listenerAnnounces]), a focused + * slider says it, or a volume key is held. While the key is held, the change is said once the key + * is released. A change soon after the last one of the same stream says only the percentage. + */ + fun onVolumeChanged(streamType: Int, listenerAnnounces: Boolean) { + val byKey = changedByVolumeKey() + // The key check comes first because finding the focused node asks the app. + if (listenerAnnounces || (!byKey && sliderFocused.asBoolean)) return + // Nothing is said, so the next change after the call names the volume again. + if (isInCall()) return + val now = SystemClock.uptimeMillis() + val brief = streamType == lastChangedStream && now - lastChangeTime < SAME_STREAM_WINDOW_MS + lastChangedStream = streamType + lastChangeTime = now + // A held key repeats many times a second, so a missed release doesn't keep later changes quiet. + if (volumeKeyHeld && byKey) { + heldChange = HeldChange(streamType, brief) + return + } + announceVolumeNow(streamType, brief) + } + + /** + * Says that [streamType] was muted or unmuted, as a volume change is said. It replaces the level + * said for the same key press. A held key's level is said when the key is released. + */ + fun onStreamMuted(streamType: Int, muted: Boolean) { + val byKey = changedByVolumeKey() + // A focused slider says its own value, as it does for a volume change. + if ((volumeKeyHeld && byKey) || (!byKey && sliderFocused.asBoolean)) return + if (!monitor.speakVolumeChanges() || isInCall()) return + if (muted) { + speak(context.getString(R.string.template_stream_muted_set, monitor.getStreamName(streamType))) + } else { + speakVolume(streamType, brief = false) + } + } + + /** + * Follows a volume key that goes to apps. Holding it makes Android repeat the press, which changes + * the volume several times a second, so those changes are kept quiet and the volume is said once + * when the key is released. + */ + fun onVolumeKeyEvent(event: KeyEvent) { + if (event.action == KeyEvent.ACTION_DOWN) { + lastVolumeKeyDownTime = SystemClock.uptimeMillis() + if (event.repeatCount == 0) { + // A new press says its own change, which replaces anything a hold had left to say. + forgetHold() + } else { + volumeKeyHeld = true + } + } else if (event.action == KeyEvent.ACTION_UP && volumeKeyHeld) { + // The volume broadcast for the last repeat can still be on its way, so wait for it. + handler.removeCallbacks(announceAfterHold) + handler.postDelayed(announceAfterHold, HOLD_RELEASE_SETTLE_MS) + } + } + + private fun forgetHold() { + handler.removeCallbacks(announceAfterHold) + volumeKeyHeld = false + heldChange = null + } + + private fun changedByVolumeKey(): Boolean = + SystemClock.uptimeMillis() - lastVolumeKeyDownTime < KEY_CHANGE_WINDOW_MS + + /** @param brief whether to say only the percentage, without the stream name */ + private fun announceVolumeNow(streamType: Int, brief: Boolean) { + if (!monitor.speakVolumeChanges() || isInCall()) return + speakVolume(streamType, brief) + } + + private fun speakVolume(streamType: Int, brief: Boolean) { + speak( + if (brief) briefAnnouncement(streamType) + else monitor.getAnnouncementForStreamType(R.string.template_stream_volume_set, streamType) + ) + } + + private fun speak(text: CharSequence) { + val speakOptions = + SpeechController.SpeakOptions.create() + .setQueueMode( + if (continuousReading.asBoolean) SpeechController.QUEUE_MODE_QUEUE + else SpeechController.QUEUE_MODE_INTERRUPT + ) + .setFlags( + FeedbackItem.FLAG_SOURCE_IS_VOLUME_CONTROL or + FeedbackItem.FLAG_FORCE_FEEDBACK_EVEN_IF_AUDIO_PLAYBACK_ACTIVE or + FeedbackItem.FLAG_CLEAR_QUEUED_UTTERANCES_WITH_SAME_UTTERANCE_GROUP or + FeedbackItem.FLAG_INTERRUPT_CURRENT_UTTERANCE_WITH_SAME_UTTERANCE_GROUP + ) + .setUtteranceGroup(SpeechController.UTTERANCE_GROUP_VOLUME) + pipeline.returnFeedback(EVENT_ID_UNTRACKED, Feedback.speech(text, speakOptions)) + } + + /** + * The volume of the stream as only a percentage, for changes that follow one that already named + * the stream. The ringer still says when it's silent or vibrating. + */ + private fun briefAnnouncement(streamType: Int): String { + if ( + streamType == AudioManager.STREAM_RING && + audioManager.ringerMode != AudioManager.RINGER_MODE_NORMAL + ) { + return monitor.getAnnouncementForStreamType(R.string.template_stream_volume_set, streamType) + } + return context.getString( + R.string.tb_template_percent, + monitor.getStreamVolume(streamType).toString(), + ) + } + + private fun isInCall(): Boolean = callStateMonitor?.isPhoneCallActive == true + + /** The devices [streamType] plays on, by ID and type. A device that reconnects gets a new ID. */ + private fun outputOf(streamType: Int): Set>? = + audioManager.outputsFor(attributesOf(streamType))?.map { it.id to it.type }?.toSet() + + private class HeldChange(val streamType: Int, val brief: Boolean) + + /** A stream's volume and the devices it played on, null when Android couldn't say. */ + private class StreamLevel(val output: Set>?, val volume: Int) + + private companion object { + /** How long to wait after a held volume key is released before saying the volume. */ + const val HOLD_RELEASE_SETTLE_MS = 100L + + /** How soon a change has to follow the last one of the same stream to say only the percentage. */ + const val SAME_STREAM_WINDOW_MS = 2000L + + /** How soon a change has to follow a volume key press to count as caused by it. */ + const val KEY_CHANGE_WINDOW_MS = 1000L + + /** + * The streams whose level Android keeps for each output and switches when headphones connect + * or disconnect: media, calls, notifications and accessibility. The ringer keeps one level. + */ + val PER_OUTPUT_STREAMS = + setOf( + AudioManager.STREAM_MUSIC, + AudioManager.STREAM_VOICE_CALL, + AudioManager.STREAM_NOTIFICATION, + AudioManager.STREAM_ACCESSIBILITY, + ) + } +} + +/** + * The audio attributes that play like [streamType], to find where it plays. Android won't make them + * from the accessibility stream, so that one uses the accessibility usage. + */ +internal fun attributesOf(streamType: Int): AudioAttributes = + if (streamType == AudioManager.STREAM_ACCESSIBILITY) { + AudioAttributes.Builder().setUsage(AudioAttributes.USAGE_ASSISTANCE_ACCESSIBILITY).build() + } else { + AudioAttributes.Builder().setLegacyStreamType(streamType).build() + } diff --git a/talkback/src/main/java/com/google/android/accessibility/talkback/monitor/VolumeMonitor.java b/talkback/src/main/java/com/google/android/accessibility/talkback/monitor/VolumeMonitor.java index 383e698c9..f8aec5e06 100644 --- a/talkback/src/main/java/com/google/android/accessibility/talkback/monitor/VolumeMonitor.java +++ b/talkback/src/main/java/com/google/android/accessibility/talkback/monitor/VolumeMonitor.java @@ -18,7 +18,6 @@ import static com.google.android.accessibility.utils.Performance.EVENT_ID_UNTRACKED; import static com.google.android.accessibility.utils.output.FeedbackItem.FLAG_FORCE_FEEDBACK_EVEN_IF_AUDIO_PLAYBACK_ACTIVE; -import static com.google.android.accessibility.utils.output.FeedbackItem.FLAG_SOURCE_IS_VOLUME_CONTROL; import android.annotation.SuppressLint; import android.content.Context; @@ -28,6 +27,7 @@ import android.os.Message; import android.telephony.TelephonyManager; import android.util.SparseIntArray; +import android.view.KeyEvent; import androidx.annotation.VisibleForTesting; import com.google.android.accessibility.talkback.Feedback; import com.google.android.accessibility.talkback.Feedback.Part; @@ -37,7 +37,6 @@ import com.google.android.accessibility.talkback.R; import com.google.android.accessibility.utils.FeatureSupport; import com.google.android.accessibility.utils.FormFactorUtils; -import com.google.android.accessibility.utils.Performance.EventId; import com.google.android.accessibility.utils.SharedPreferencesUtils; import com.google.android.accessibility.utils.WeakReferenceHandler; import com.google.android.accessibility.utils.broadcast.SameThreadBroadcastReceiver; @@ -49,6 +48,7 @@ import java.time.Duration; import java.util.ArrayList; import java.util.List; +import java.util.function.BooleanSupplier; /** Listens for and responds to volume changes. */ public class VolumeMonitor extends SameThreadBroadcastReceiver { @@ -64,6 +64,11 @@ public class VolumeMonitor extends SameThreadBroadcastReceiver { public interface VolumeChangedListener { /** Invoked when the volume has been changed. */ void onVolumeChanged(int type, int value, int prevValue, int percent); + + /** Backtalk: whether this listener says the new volume of {@code type} itself. */ + default boolean announcesVolume(int type) { + return false; + } } private static final SparseIntArray STREAM_NAMES = new SparseIntArray(); @@ -89,6 +94,7 @@ public interface VolumeChangedListener { private final FeedbackReturner pipeline; private final AudioManager audioManager; private final CallStateMonitor callStateMonitor; + private final VolumeAnnouncer volumeAnnouncer; private int cachedAccessibilityStreamVolume = -1; private int cachedAccessibilityStreamMaxVolume = -1; @@ -117,6 +123,17 @@ public VolumeMonitor( audioManager = (AudioManager) context.getSystemService(Context.AUDIO_SERVICE); this.callStateMonitor = callStateMonitor; this.hintA11yVolumeControl = FeatureSupport.hasAccessibilityAudioStream(context); + volumeAnnouncer = new VolumeAnnouncer(context, pipeline, callStateMonitor, this); + } + + /** Backtalk: tells the monitor how to find out whether accessibility focus is on a slider. */ + public void setSliderFocused(BooleanSupplier sliderFocused) { + volumeAnnouncer.setSliderFocused(sliderFocused); + } + + /** Backtalk: tells the monitor how to find out whether continuous reading is on. */ + public void setContinuousReading(BooleanSupplier continuousReading) { + volumeAnnouncer.setContinuousReading(continuousReading); } public void addVolumeChangedListener(VolumeChangedListener listener) { @@ -131,10 +148,14 @@ public void clearVolumeChangedListener() { listeners.clear(); } - private void notifyVolumeChangedListener(int type, int value, int prevValue, int percent) { + /** Backtalk: returns whether a listener says the new volume itself. */ + private boolean notifyVolumeChangedListener(int type, int value, int prevValue, int percent) { + boolean announced = false; for (VolumeChangedListener listener : listeners) { + announced |= listener.announcesVolume(type); listener.onVolumeChanged(type, value, prevValue, percent); } + return announced; } public IntentFilter getFilter() { @@ -181,13 +202,23 @@ private void internalOnVolumeChanged(int streamType, int volume, int prevVolume) } } - notifyVolumeChangedListener(streamType, volume, prevVolume, getStreamVolume(streamType)); + // Backtalk: a gesture or reading control that changed the volume is listening, and says the + // new volume itself. + boolean listenerAnnounces = + notifyVolumeChangedListener(streamType, volume, prevVolume, getStreamVolume(streamType)); + + // Backtalk: a level that a new output brings isn't the user's change, unless a listener was + // waiting for it. + if (volumeAnnouncer.isIgnoredChange(streamType, volume) && !listenerAnnounces) { + return; + } if (currentStream < 0) { // If the current stream hasn't been set, acquire control. currentStream = streamType; AudioManagerCompatUtils.forceVolumeControlStream(audioManager, currentStream); handler.onControlAcquired(streamType); + volumeAnnouncer.onVolumeChanged(streamType, listenerAnnounces); return; } @@ -196,9 +227,15 @@ private void internalOnVolumeChanged(int streamType, int volume, int prevVolume) return; } + volumeAnnouncer.onVolumeChanged(streamType, listenerAnnounces); handler.releaseControlDelayed(); } + /** Backtalk: follows a volume key that goes to apps, so a held key is said once. */ + public void onVolumeKeyEvent(KeyEvent event) { + volumeAnnouncer.onVolumeKeyEvent(event); + } + /** * Called after audio stream muted. Handles current stream and providing feedback. Currently, it * works with STREAM_MUSIC only. @@ -211,18 +248,9 @@ private void internalOnStreamMuted(int streamType, boolean mutedState) { return; } - String text; - if (mutedState) { - text = context.getString(R.string.template_stream_muted_set, getStreamName(streamType)); - } else { - text = getAnnouncementForStreamType(R.string.template_stream_volume_set, streamType); - } - - if (!shouldAnnounceStream(streamType)) { - handler.post(this::releaseControl); - return; - } - speakWithCompletion(text, streamType, utteranceCompleteRunnable, EVENT_ID_UNTRACKED); + // Backtalk: said the way volume changes are, while media plays too. + volumeAnnouncer.onStreamMuted(streamType, mutedState); + handler.post(this::releaseControl); } private void internalSpeakA11yVolumeControlHint() { @@ -283,6 +311,16 @@ private void increaseAndStoreA11yVolumeControlHintTimes(int times) { } } + /** Backtalk: starts following outputs, which bring their own volume levels. */ + public void startAnnouncing() { + volumeAnnouncer.start(); + } + + /** Backtalk: stops following outputs, and drops a volume still to be said. */ + public void stopAnnouncing() { + volumeAnnouncer.stop(); + } + public void cacheAccessibilityStreamVolume() { cachedAccessibilityStreamVolume = audioManager.getStreamVolume(AudioManager.STREAM_ACCESSIBILITY); @@ -315,7 +353,7 @@ private void internalOnControlAcquired(int streamType) { * @param streamType The stream to announce. * @return The volume announcement text for the stream. */ - private String getAnnouncementForStreamType(int templateResId, int streamType) { + String getAnnouncementForStreamType(int templateResId, int streamType) { // The ringer has special cases for silent and vibrate. if (streamType == AudioManager.STREAM_RING) { switch (audioManager.getRingerMode()) { @@ -337,7 +375,8 @@ private String getAnnouncementForStreamType(int templateResId, int streamType) { /** * Called after adjustments have been made and the user has not taken any action for a certain - * duration. Announces the current volume and releases control of the stream. + * duration. Backtalk: says the accessibility volume hint, if it's still due, and releases control + * of the stream. */ private void internalOnReleaseControl() { handler.clearReleaseControl(); @@ -350,16 +389,12 @@ private void internalOnReleaseControl() { LogUtils.v(TAG, "Released control of stream %d", currentStream); - if (!shouldAnnounceStream(streamType) || !speakVolumeChanges()) { - handler.post(this::releaseControl); - return; + // Backtalk: the volume was already said as it changed, so only the hint on how to change the + // accessibility volume is left to say. + if (speakVolumeChanges() && streamType != SpeechController.DEFAULT_STREAM) { + internalSpeakA11yVolumeControlHint(); } - - final String text = - getAnnouncementForStreamType(R.string.template_stream_volume_set, streamType); - - EventId eventId = EVENT_ID_UNTRACKED; // Delayed feedback occurs after normal feedback. - speakWithCompletion(text, streamType, utteranceCompleteRunnable, eventId); + releaseControl(); } /** Releases control of the stream. */ @@ -368,14 +403,8 @@ public void releaseControl() { AudioManagerCompatUtils.forceVolumeControlStream(audioManager, -1); } - /** - * Returns whether a stream type should be announced. - * - * @param streamType The stream type. - * @return True if the stream should be announced. - */ /** Whether the user wants the new volume said after they change it. */ - private boolean speakVolumeChanges() { + boolean speakVolumeChanges() { return SharedPreferencesUtils.getBooleanPref( SharedPreferencesUtils.getSharedPreferences(context), context.getResources(), @@ -383,70 +412,6 @@ private boolean speakVolumeChanges() { R.bool.pref_speak_volume_changes_default); } - private boolean shouldAnnounceStream(int streamType) { - return switch (streamType) { - case AudioManager.STREAM_MUSIC -> - // Only announce music stream if it's not being used. - !audioManager.isMusicActive(); - default -> - // Announce all other streams by default. The VOICE_CALL and - // RING streams are handled by checking the telephony state in - // speakWithCompletion(). - true; - }; - } - - /** - * Speaks text with a completion action, or just runs the completion action if the volume monitor - * should be quiet. - * - * @param text The text to speak. - * @param streamType The type of stream. - * @param completedAction The action to run after speaking. - */ - private void speakWithCompletion( - String text, - int streamType, - SpeechController.UtteranceCompleteRunnable completedAction, - EventId eventId) { - if ((callStateMonitor != null) - && (callStateMonitor.getCurrentCallState() != TelephonyManager.CALL_STATE_IDLE)) { - // If the phone is busy, don't speak anything. - handler.post(this::releaseControl); - return; - } - - SpeechController.SpeakOptions speakOptions = - SpeechController.SpeakOptions.create() - .setQueueMode(SpeechController.QUEUE_MODE_QUEUE) - .setFlags( - FLAG_SOURCE_IS_VOLUME_CONTROL | FLAG_FORCE_FEEDBACK_EVEN_IF_AUDIO_PLAYBACK_ACTIVE) - .setUtteranceGroup(SpeechController.UTTERANCE_GROUP_DEFAULT) - .setCompletedAction(completedAction); - Speech.Builder speechBuilder = - Speech.builder().setAction(Action.SPEAK).setText(text).setOptions(speakOptions); - - // Let's speak the hint even if audio playback is active because the hint is only spoken for - // 3 times, we don't want users to miss it. - if (hintA11yVolumeControl) { - int a11yVolumeControlHintTimes = getA11yVolumeControlHintTimes(); - if ((a11yVolumeControlHintTimes < A11Y_VOLUME_CONTROL_HINT_TIMES) - && (streamType != SpeechController.DEFAULT_STREAM)) { - increaseAndStoreA11yVolumeControlHintTimes(a11yVolumeControlHintTimes); - speechBuilder - .setHintSpeakOptions( - SpeakOptions.create() - .setFlags( - FeedbackItem.FLAG_NO_HISTORY - | FLAG_FORCE_FEEDBACK_EVEN_IF_AUDIO_PLAYBACK_ACTIVE)) - .setHint(context.getString(R.string.hint_a11y_volume_control)); - } - } - - Feedback.Part.Builder part = Feedback.Part.builder().setSpeech(speechBuilder.build()); - pipeline.returnFeedback(eventId, part); - } - /** * Returns the localized stream name for a given stream type constant. * @@ -502,7 +467,7 @@ public void onReceiveIntent(Intent intent) { * @return The stream volume as a percentage. */ @SuppressLint("NewApi") - private int getStreamVolume(int streamType) { + int getStreamVolume(int streamType) { int minVolume = 0; // For some stream types other than defined in // https://developer.android.com/reference/android/media/AudioManager#getStreamMinVolume(int), @@ -528,24 +493,6 @@ private int getStreamVolume(int streamType) { private final VolumeHandler handler = new VolumeHandler(this); - /** - * Runnable that hides the volume overlay. Used as a completion action for the "volume set" - * utterance. - */ - private final SpeechController.UtteranceCompleteRunnable utteranceCompleteRunnable = - new SpeechController.UtteranceCompleteRunnable() { - @Override - public void run(int status) { - releaseControl(); - } - }; - - /** This is to check data of Feedback of Pipeline for test purpose. */ - @VisibleForTesting - SpeechController.UtteranceCompleteRunnable getUtteranceCompleteRunnable() { - return utteranceCompleteRunnable; - } - public void onVolumeKeyPressed() { handler.volumeButtonHintDelayed(); } @@ -626,8 +573,7 @@ public void volumeButtonHintDelayed() { public void clearReleaseControl() { removeMessages(MSG_CONTROL); removeMessages(MSG_RELEASE_CONTROL); - // When we announce the volume change, the a11y volume control hint will be in the volume - // value announcement. + // Backtalk: the a11y volume control hint is said when control is released. removeMessages(MSG_VOLUME_BUTTON_HINT); } diff --git a/talkback/src/main/java/com/google/android/accessibility/talkback/selector/SelectorController.java b/talkback/src/main/java/com/google/android/accessibility/talkback/selector/SelectorController.java index 18205393f..5c61073a8 100644 --- a/talkback/src/main/java/com/google/android/accessibility/talkback/selector/SelectorController.java +++ b/talkback/src/main/java/com/google/android/accessibility/talkback/selector/SelectorController.java @@ -2492,6 +2492,11 @@ private void scrollForwardBackward(EventId eventId, boolean isNext) { private final VolumeChangedListener volumeChangedListener = new VolumeChangedListener() { + @Override + public boolean announcesVolume(int type) { + return type == listenedVolumeStream; + } + @Override public void onVolumeChanged(int type, int value, int prevValue, int percent) { if (type != listenedVolumeStream) { diff --git a/talkback/src/test/java/com/google/android/accessibility/talkback/FinalAnnouncementVolumeTest.kt b/talkback/src/test/java/com/google/android/accessibility/talkback/FinalAnnouncementVolumeTest.kt index d36b60537..04ef8aac4 100644 --- a/talkback/src/test/java/com/google/android/accessibility/talkback/FinalAnnouncementVolumeTest.kt +++ b/talkback/src/test/java/com/google/android/accessibility/talkback/FinalAnnouncementVolumeTest.kt @@ -42,6 +42,37 @@ class FinalAnnouncementVolumeTest { assertTrue(measured < guessed / 2f) } + @Test + fun decibelsAreUsedAsTheyAre() { + assertEquals(0.1f, FinalAnnouncementVolume.gainFromReportedVolumes(-40f, -20f), 1e-4f) + assertEquals(0.1f, FinalAnnouncementVolume.gainFromReportedVolumes(-20f, 0f), 1e-4f) + // A volume curve that boosts media above 0 dB is still in decibels. + assertEquals(0.1f, FinalAnnouncementVolume.gainFromReportedVolumes(-18f, 2f), 1e-4f) + assertEquals(0.7943f, FinalAnnouncementVolume.gainFromReportedVolumes(0f, 2f), 1e-4f) + } + + @Test + fun samsungsFractionsOfFullLoudnessAreDivided() { + // A Samsung phone on its speaker: accessibility volume 4 and media volume 7 out of 15. + assertEquals(0.1288f, FinalAnnouncementVolume.gainFromReportedVolumes(0.01f, 0.0776f), 1e-4f) + assertEquals(1f, FinalAnnouncementVolume.gainFromReportedVolumes(1f, 0.0776f), 0f) + assertEquals(1f, FinalAnnouncementVolume.gainFromReportedVolumes(1f, 1f), 0f) + } + + @Test + fun mediaStepsAreMatchedToAccessibilitySteps() { + // Media from step 0 and accessibility from step 1, both to 15, as on a Samsung phone, where + // media 7 set accessibility 8 and media 8 set it to 9. + assertEquals(8, FinalAnnouncementVolume.accessibilityStepAtMediaVolume(7, 0, 15, 1, 15)) + assertEquals(9, FinalAnnouncementVolume.accessibilityStepAtMediaVolume(8, 0, 15, 1, 15)) + // The emulator: media 9 set accessibility 9. + assertEquals(9, FinalAnnouncementVolume.accessibilityStepAtMediaVolume(9, 0, 15, 1, 15)) + assertEquals(15, FinalAnnouncementVolume.accessibilityStepAtMediaVolume(15, 0, 15, 1, 15)) + assertEquals(9, FinalAnnouncementVolume.accessibilityStepAtMediaVolume(9, 0, 15, 0, 15)) + assertEquals(3, FinalAnnouncementVolume.accessibilityStepAtMediaVolume(5, 0, 25, 0, 15)) + assertEquals(15, FinalAnnouncementVolume.accessibilityStepAtMediaVolume(25, 0, 25, 0, 15)) + } + @Test fun sliderGuessKeepsTalkBackBehavior() { assertEquals(1f, FinalAnnouncementVolume.sliderGain(0.6f, 0.4f), 0f) diff --git a/talkback/src/test/java/com/google/android/accessibility/talkback/monitor/VolumeMonitorTest.kt b/talkback/src/test/java/com/google/android/accessibility/talkback/monitor/VolumeMonitorTest.kt new file mode 100644 index 000000000..8432a1f9e --- /dev/null +++ b/talkback/src/test/java/com/google/android/accessibility/talkback/monitor/VolumeMonitorTest.kt @@ -0,0 +1,549 @@ +/* + * Copyright 2026 Backtalk contributors + * + * Licensed under the Apache License, Version 2.0 (the "License"); you may not + * use this file except in compliance with the License. You may obtain a copy of + * the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + * License for the specific language governing permissions and limitations under + * the License. + */ + +package com.google.android.accessibility.talkback.monitor + +import android.content.Context +import android.content.Intent +import android.media.AudioDeviceInfo +import android.media.AudioManager +import android.media.AudioManager.STREAM_ACCESSIBILITY +import android.media.AudioManager.STREAM_MUSIC +import android.media.AudioManager.STREAM_NOTIFICATION +import android.media.AudioManager.STREAM_VOICE_CALL +import android.os.Looper +import android.view.KeyEvent +import com.google.android.accessibility.talkback.Feedback +import com.google.android.accessibility.talkback.Pipeline +import com.google.android.accessibility.talkback.R +import com.google.android.accessibility.utils.FormFactorUtils +import com.google.android.accessibility.utils.SharedPreferencesUtils +import com.google.android.accessibility.utils.compat.media.AudioManagerCompatUtils +import com.google.android.accessibility.utils.output.SpeechController +import com.google.common.collect.ImmutableList +import java.time.Duration +import org.junit.Assert.assertEquals +import org.junit.Before +import org.junit.Test +import org.junit.runner.RunWith +import org.robolectric.RobolectricTestRunner +import org.robolectric.RuntimeEnvironment +import org.robolectric.Shadows.shadowOf +import org.robolectric.annotation.Config +import org.robolectric.shadows.AudioDeviceInfoBuilder + +@RunWith(RobolectricTestRunner::class) +@Config(sdk = [34]) +class VolumeMonitorTest { + private val context: Context + get() = RuntimeEnvironment.getApplication() + + private val spoken = mutableListOf() + private val pipeline = + object : Pipeline.FeedbackReturner { + override fun returnFeedback(feedback: Feedback): Boolean { + feedback.failovers().first().speech()?.let { spoken += it } + return true + } + } + + private lateinit var audioManager: AudioManager + private lateinit var monitor: VolumeMonitor + + @Before + fun setUp() { + FormFactorUtils.initialize(context) + audioManager = context.getSystemService(Context.AUDIO_SERVICE) as AudioManager + shadowOf(audioManager).setStreamMaxVolume(10) + // Without this, the first changes also teach how to change the accessibility volume. + SharedPreferencesUtils.putIntPref( + SharedPreferencesUtils.getSharedPreferences(context), + context.resources, + R.string.pref_a11y_volume_control_hint_times, + 3, + ) + monitor = VolumeMonitor(pipeline, context, null) + } + + @Test + fun eachChangeIsSaidRightAway() { + change(STREAM_MUSIC, 5, 4) + change(STREAM_MUSIC, 6, 5) + + assertEquals( + listOf("Music volume set to 50 percent.", "60 percent"), + texts(), + ) + spoken.forEach { + assertEquals(SpeechController.UTTERANCE_GROUP_VOLUME, it.options()!!.mUtteranceGroup) + assertEquals(SpeechController.QUEUE_MODE_INTERRUPT, it.options()!!.mQueueMode) + } + } + + @Test + fun aChangeAfterAPauseNamesTheVolumeAgain() { + change(STREAM_MUSIC, 5, 4) + shadowOf(Looper.getMainLooper()).idleFor(Duration.ofSeconds(3)) + change(STREAM_MUSIC, 6, 5) + + assertEquals( + listOf("Music volume set to 50 percent.", "Music volume set to 60 percent."), + texts(), + ) + } + + @Test + fun aChangeToAnotherVolumeNamesIt() { + change(STREAM_MUSIC, 5, 4) + change(STREAM_ACCESSIBILITY, 5, 4) + + assertEquals( + listOf("Music volume set to 50 percent.", "Accessibility volume set to 50 percent."), + texts(), + ) + } + + @Test + fun continuousReadingIsNotInterrupted() { + monitor.setContinuousReading { true } + + change(STREAM_MUSIC, 5, 4) + + assertEquals(SpeechController.QUEUE_MODE_QUEUE, spoken.single().options()!!.mQueueMode) + } + + @Test + fun aFocusedSliderSaysItsOwnValue() { + monitor.setSliderFocused { true } + + change(STREAM_MUSIC, 5, 4) + + assertEquals(emptyList(), texts()) + } + + @Test + fun theVolumeKeysAreSaidOnAFocusedSlider() { + monitor.setSliderFocused { true } + + key(KeyEvent.ACTION_DOWN, repeat = 0) + change(STREAM_MUSIC, 5, 4) + + assertEquals(listOf("Music volume set to 50 percent."), texts()) + } + + @Test + fun theMediaVolumeIsSaidWhileMediaPlays() { + shadowOf(audioManager).setIsMusicActive(true) + + change(STREAM_MUSIC, 5, 4) + + assertEquals(listOf("Music volume set to 50 percent."), texts()) + } + + @Test + fun theVolumeHeadphonesSetWhenTheyConnectIsNotSaid() { + monitor.startAnnouncing() + // Android can report the headphones' level before it says they connected. + playMediaOn(headphones()) + + change(STREAM_MUSIC, 5, 4) + + assertEquals(emptyList(), texts()) + } + + @Test + fun theHeadphonesRepeatingTheirLevelIsNotSaid() { + monitor.startAnnouncing() + playMediaOn(headphones()) + + change(STREAM_MUSIC, 5, 4) + change(STREAM_MUSIC, 5, 5) + + assertEquals(emptyList(), texts()) + } + + @Test + fun aVolumeKeyAtTheSameLevelIsSaid() { + monitor.startAnnouncing() + change(STREAM_MUSIC, 10, 9) + spoken.clear() + shadowOf(Looper.getMainLooper()).idleFor(Duration.ofSeconds(10)) + + key(KeyEvent.ACTION_DOWN, repeat = 0) + change(STREAM_MUSIC, 10, 10) + + assertEquals(listOf("Music volume set to 100 percent."), texts()) + } + + @Test + fun anUnchangedVolumeThatNoKeyMadeIsNotSaid() { + change(STREAM_MUSIC, 10, 9) + shadowOf(Looper.getMainLooper()).idleFor(Duration.ofMillis(500)) + spoken.clear() + + change(STREAM_MUSIC, 10, 10) + + assertEquals(emptyList(), texts()) + } + + @Test + fun muteIsSaidLikeAVolumeChange() { + mute(true) + + assertEquals(listOf("Music volume muted."), texts()) + assertEquals(SpeechController.UTTERANCE_GROUP_VOLUME, spoken.single().options()?.mUtteranceGroup) + } + + @Test + fun muteIsNotSaidWhenSpeakVolumeChangesIsOff() { + SharedPreferencesUtils.putBooleanPref( + SharedPreferencesUtils.getSharedPreferences(context), + context.resources, + R.string.pref_speak_volume_changes_key, + false, + ) + + mute(true) + + assertEquals(emptyList(), texts()) + } + + @Test + fun aListenerHearsAChangeThatComesWithANewOutput() { + monitor.startAnnouncing() + playMediaOn(headphones()) + var heard = 0 + monitor.addVolumeChangedListener( + object : VolumeMonitor.VolumeChangedListener { + override fun onVolumeChanged(type: Int, value: Int, prevValue: Int, percent: Int) { + heard++ + } + + override fun announcesVolume(type: Int) = type == STREAM_MUSIC + } + ) + + change(STREAM_MUSIC, 5, 4) + + assertEquals(1, heard) + assertEquals(emptyList(), texts()) + } + + @Test + fun theAccessibilityLevelHeadphonesBringIsNotSaid() { + monitor.startAnnouncing() + playOn(STREAM_ACCESSIBILITY, headphones()) + + change(STREAM_ACCESSIBILITY, 9, 3) + + assertEquals(emptyList(), texts()) + } + + @Test + fun aVolumeKeyIsSaidOnANewOutput() { + monitor.startAnnouncing() + playMediaOn(headphones()) + + key(KeyEvent.ACTION_DOWN, repeat = 0) + change(STREAM_MUSIC, 5, 4) + + assertEquals(listOf("Music volume set to 50 percent."), texts()) + } + + @Test + fun theHeadphoneControlsAreSaidAfterTheHeadphonesSetTheirVolume() { + monitor.startAnnouncing() + playMediaOn(headphones()) + + change(STREAM_MUSIC, 5, 4) + change(STREAM_MUSIC, 6, 5) + + assertEquals(listOf("Music volume set to 60 percent."), texts()) + } + + @Test + fun theSpeakerLevelIsNotSaidWhenHeadphonesDisconnect() { + monitor.startAnnouncing() + playMediaOn(headphones()) + change(STREAM_MUSIC, 5, 4) + playMediaOn(speaker()) + + change(STREAM_MUSIC, 3, 5) + change(STREAM_MUSIC, 4, 3) + + assertEquals(listOf("Music volume set to 40 percent."), texts()) + } + + @Test + fun theCallAndNotificationLevelsHeadphonesSetWhenTheyConnectAreNotSaid() { + monitor.startAnnouncing() + playOn(STREAM_VOICE_CALL, headphones()) + playOn(STREAM_NOTIFICATION, headphones()) + + change(STREAM_VOICE_CALL, 9, 1) + change(STREAM_NOTIFICATION, 3, 9) + + assertEquals(emptyList(), texts()) + } + + @Test + fun theCallVolumeIsSaidAfterTheHeadphonesSetIt() { + monitor.startAnnouncing() + playOn(STREAM_VOICE_CALL, headphones()) + + change(STREAM_VOICE_CALL, 9, 1) + change(STREAM_VOICE_CALL, 8, 9) + + assertEquals(listOf("Phone call volume set to 80 percent."), texts()) + } + + @Test + fun headphonesConnectedBeforeBacktalkStartsAreNotWaitedFor() { + playMediaOn(headphones()) + monitor.startAnnouncing() + + change(STREAM_MUSIC, 5, 4) + + assertEquals(listOf("Music volume set to 50 percent."), texts()) + } + + @Test + fun theAccessibilityVolumeIsKeptWhenItMovesToAnotherOutput() { + monitor.startAnnouncing() + monitor.cacheAccessibilityStreamVolume() + audioManager.setStreamVolume(STREAM_ACCESSIBILITY, 3, 0) + + context.sendBroadcast( + Intent(AudioManagerCompatUtils.STREAM_DEVICES_CHANGED_ACTION) + .setPackage(context.packageName) + .putExtra(AudioManagerCompatUtils.EXTRA_VOLUME_STREAM_TYPE, STREAM_ACCESSIBILITY) + ) + shadowOf(Looper.getMainLooper()).idle() + + assertEquals(3, monitor.cachedAccessibilityStreamVolume) + } + + @Test + fun nothingMoreIsSaidWhenTheKeysAreStill() { + change(STREAM_MUSIC, 5, 4) + spoken.clear() + + shadowOf(Looper.getMainLooper()).idleFor(Duration.ofSeconds(10)) + + assertEquals(emptyList(), texts()) + } + + @Test + fun aGestureThatSaysTheVolumeItselfIsNotSpokenOver() { + var heard = 0 + monitor.addVolumeChangedListener( + object : VolumeMonitor.VolumeChangedListener { + override fun onVolumeChanged(type: Int, value: Int, prevValue: Int, percent: Int) { + heard++ + } + + override fun announcesVolume(type: Int) = type == STREAM_ACCESSIBILITY + } + ) + + change(STREAM_ACCESSIBILITY, 5, 4) + + assertEquals(1, heard) + assertEquals(emptyList(), texts()) + } + + @Test + fun aListenerThatDoesNotSayTheVolumeDoesNotSilenceIt() { + monitor.addVolumeChangedListener { _, _, _, _ -> } + + change(STREAM_ACCESSIBILITY, 5, 4) + + assertEquals(listOf("Accessibility volume set to 50 percent."), texts()) + } + + @Test + fun aMediaVolumeReadingControlIsNotSpokenOver() { + monitor.addVolumeChangedListener( + object : VolumeMonitor.VolumeChangedListener { + override fun onVolumeChanged(type: Int, value: Int, prevValue: Int, percent: Int) {} + + override fun announcesVolume(type: Int) = type == STREAM_MUSIC + } + ) + + change(STREAM_MUSIC, 5, 4) + + assertEquals(emptyList(), texts()) + } + + @Test + fun anAccessibilityVolumeListenerDoesNotSilenceTheMediaVolumeKeys() { + monitor.addVolumeChangedListener( + object : VolumeMonitor.VolumeChangedListener { + override fun onVolumeChanged(type: Int, value: Int, prevValue: Int, percent: Int) {} + + override fun announcesVolume(type: Int) = type == STREAM_ACCESSIBILITY + } + ) + + change(STREAM_MUSIC, 5, 4) + + assertEquals(listOf("Music volume set to 50 percent."), texts()) + } + + @Test + fun theAccessibilityVolumeHintIsSaidWhenTheKeysAreStill() { + SharedPreferencesUtils.putIntPref( + SharedPreferencesUtils.getSharedPreferences(context), + context.resources, + R.string.pref_a11y_volume_control_hint_times, + 0, + ) + monitor = VolumeMonitor(pipeline, context, null) + change(STREAM_MUSIC, 5, 4) + spoken.clear() + + shadowOf(Looper.getMainLooper()).idleFor(Duration.ofSeconds(10)) + + assertEquals( + listOf(context.getString(R.string.hint_a11y_volume_control)), + spoken.map { it.hint().toString() }, + ) + } + + @Test + fun nothingIsSaidWhenSpeakVolumeChangesIsOff() { + SharedPreferencesUtils.putBooleanPref( + SharedPreferencesUtils.getSharedPreferences(context), + context.resources, + R.string.pref_speak_volume_changes_key, + false, + ) + + change(STREAM_MUSIC, 5, 4) + + assertEquals(emptyList(), texts()) + } + + @Test + fun holdingTheKeySaysOnlyTheLevelItEndsAt() { + key(KeyEvent.ACTION_DOWN, repeat = 0) + change(STREAM_MUSIC, 5, 4) + key(KeyEvent.ACTION_DOWN, repeat = 1) + change(STREAM_MUSIC, 6, 5) + key(KeyEvent.ACTION_DOWN, repeat = 2) + change(STREAM_MUSIC, 7, 6) + + assertEquals(listOf("Music volume set to 50 percent."), texts()) + + key(KeyEvent.ACTION_UP) + shadowOf(Looper.getMainLooper()).idleFor(Duration.ofMillis(200)) + + assertEquals( + listOf("Music volume set to 50 percent.", "70 percent"), + texts(), + ) + } + + @Test + fun aChangeThatArrivesJustAfterTheReleaseIsSaidOnce() { + key(KeyEvent.ACTION_DOWN, repeat = 0) + change(STREAM_MUSIC, 5, 4) + key(KeyEvent.ACTION_DOWN, repeat = 1) + key(KeyEvent.ACTION_UP) + change(STREAM_MUSIC, 6, 5) + shadowOf(Looper.getMainLooper()).idleFor(Duration.ofMillis(200)) + + assertEquals( + listOf("Music volume set to 50 percent.", "60 percent"), + texts(), + ) + } + + @Test + fun aHoldWithoutAChangeSaysNothingMore() { + key(KeyEvent.ACTION_DOWN, repeat = 0) + change(STREAM_MUSIC, 10, 9) + key(KeyEvent.ACTION_DOWN, repeat = 1) + key(KeyEvent.ACTION_UP) + shadowOf(Looper.getMainLooper()).idleFor(Duration.ofMillis(200)) + + assertEquals(listOf("Music volume set to 100 percent."), texts()) + } + + @Test + fun aPressAfterAHoldIsSaidRightAway() { + key(KeyEvent.ACTION_DOWN, repeat = 0) + change(STREAM_MUSIC, 5, 4) + key(KeyEvent.ACTION_DOWN, repeat = 1) + change(STREAM_MUSIC, 6, 5) + key(KeyEvent.ACTION_UP) + shadowOf(Looper.getMainLooper()).idleFor(Duration.ofMillis(200)) + key(KeyEvent.ACTION_DOWN, repeat = 0) + change(STREAM_MUSIC, 7, 6) + + assertEquals( + listOf( + "Music volume set to 50 percent.", + "60 percent", + "70 percent", + ), + texts(), + ) + } + + private fun key(action: Int, repeat: Int = 0) { + monitor.onVolumeKeyEvent(KeyEvent(0, 0, action, KeyEvent.KEYCODE_VOLUME_UP, repeat)) + } + + private fun change(stream: Int, value: Int, prevValue: Int) { + audioManager.setStreamVolume(stream, value, 0) + monitor.onReceiveIntent( + Intent(AudioManagerCompatUtils.VOLUME_CHANGED_ACTION) + .putExtra(AudioManagerCompatUtils.EXTRA_VOLUME_STREAM_TYPE, stream) + .putExtra(AudioManagerCompatUtils.EXTRA_VOLUME_STREAM_VALUE, value) + .putExtra(AudioManagerCompatUtils.EXTRA_PREV_VOLUME_STREAM_VALUE, prevValue) + ) + // Runs what is already due, without letting any time pass. + shadowOf(Looper.getMainLooper()).idle() + } + + private fun mute(muted: Boolean) { + monitor.onReceiveIntent( + Intent(AudioManagerCompatUtils.STREAM_MUTE_CHANGED_ACTION) + .putExtra(AudioManagerCompatUtils.EXTRA_VOLUME_STREAM_TYPE, STREAM_MUSIC) + .putExtra(AudioManagerCompatUtils.EXTRA_STREAM_VOLUME_MUTED, muted) + ) + shadowOf(Looper.getMainLooper()).idle() + } + + private fun headphones(): AudioDeviceInfo = + AudioDeviceInfoBuilder.newBuilder().setType(AudioDeviceInfo.TYPE_BLUETOOTH_A2DP).build() + + private fun speaker(): AudioDeviceInfo = + AudioDeviceInfoBuilder.newBuilder().setType(AudioDeviceInfo.TYPE_BUILTIN_SPEAKER).build() + + private fun playMediaOn(device: AudioDeviceInfo) { + playOn(STREAM_MUSIC, device) + } + + private fun playOn(stream: Int, device: AudioDeviceInfo) { + shadowOf(audioManager) + .setAudioDevicesForAttributes(attributesOf(stream), ImmutableList.of(device)) + } + + private fun texts() = spoken.map { it.text().toString() } +} diff --git a/utils/src/main/java/com/google/android/accessibility/utils/compat/media/AudioManagerCompatUtils.java b/utils/src/main/java/com/google/android/accessibility/utils/compat/media/AudioManagerCompatUtils.java index 63281b320..af38df78b 100644 --- a/utils/src/main/java/com/google/android/accessibility/utils/compat/media/AudioManagerCompatUtils.java +++ b/utils/src/main/java/com/google/android/accessibility/utils/compat/media/AudioManagerCompatUtils.java @@ -61,6 +61,10 @@ public class AudioManagerCompatUtils { public static final String STREAM_MUTE_CHANGED_ACTION = "android.media.STREAM_MUTE_CHANGED_ACTION"; + /** Backtalk: sent after a stream moves to other outputs, with {@link #EXTRA_VOLUME_STREAM_TYPE}. */ + public static final String STREAM_DEVICES_CHANGED_ACTION = + "android.media.STREAM_DEVICES_CHANGED_ACTION"; + /** The mute statefor the stream mute changed intent. */ public static final String EXTRA_STREAM_VOLUME_MUTED = "android.media.EXTRA_STREAM_VOLUME_MUTED"; diff --git a/utils/src/main/java/com/google/android/accessibility/utils/output/SpeechController.java b/utils/src/main/java/com/google/android/accessibility/utils/output/SpeechController.java index fad6e442e..300d7108e 100644 --- a/utils/src/main/java/com/google/android/accessibility/utils/output/SpeechController.java +++ b/utils/src/main/java/com/google/android/accessibility/utils/output/SpeechController.java @@ -143,6 +143,8 @@ public interface SpeechController { int UTTERANCE_GROUP_CONTENT_HINTS = 6; // Backtalk: speech that other apps ask for, so that it can be replaced or stopped on its own. int UTTERANCE_GROUP_OTHER_APPS = 7; + // Backtalk: the new volume, said each time it changes, so that a newer level replaces an older one. + int UTTERANCE_GROUP_VOLUME = 8; /** Enumeration of utterance-group values. */ @IntDef({ @@ -153,7 +155,8 @@ public interface SpeechController { UTTERANCE_GROUP_SCREEN_MAGNIFICATION, UTTERANCE_GROUP_CONTENT_CHANGE, UTTERANCE_GROUP_CONTENT_HINTS, - UTTERANCE_GROUP_OTHER_APPS + UTTERANCE_GROUP_OTHER_APPS, + UTTERANCE_GROUP_VOLUME }) @Retention(RetentionPolicy.SOURCE) public @interface UtteranceGroup {} @@ -434,6 +437,7 @@ public static boolean hasQueueModeFlagSet(int queueMode, int flag) { case UTTERANCE_GROUP_CONTENT_CHANGE -> "UTTERANCE_GROUP_CONTENT_CHANGE"; case UTTERANCE_GROUP_CONTENT_HINTS -> "UTTERANCE_GROUP_CONTENT_HINTS"; case UTTERANCE_GROUP_OTHER_APPS -> "UTTERANCE_GROUP_OTHER_APPS"; + case UTTERANCE_GROUP_VOLUME -> "UTTERANCE_GROUP_VOLUME"; default -> "(unknown utterance group)"; }; }