feat: practise by typing, not by pressing buttons

CHANGELOG.md

@@ -11,6 +11,29 @@ it needs to read like release notes rather than a commit log.
 
 ## [Unreleased]
 
+### Changed
+
+- Listening practice is driven by typing rather than by buttons. The sentence
+  plays as soon as you reach it; your answer is marked the moment it is as long
+  as the sentence; and a correct one moves to the next sentence by itself.
+  Check, Play and Next phrase are all still there for the times that is not
+  what you wanted — they are no longer the way through.
+- Pausing a sentence and starting it again picks up a couple of seconds before
+  where it stopped rather than at the beginning, the way a podcast player does.
+  Starting a long sentence over every time you paused to think made one
+  impossible to finish.
+- The writing field asks the system for a Chinese input source while it has
+  focus, so practising does not mean switching input source twice a sentence.
+- Every character you got wrong now carries its pinyin, beside what you typed —
+  the reading is the thing worth taking away from a mistake.
+
+### Fixed
+
+- Sentences no longer begin mid-word. Phrase playback seeked with a tenth of a
+  second of tolerance, which is inaudible when dragging a scrubber through a
+  narration and very audible when the target is the first syllable of a
+  sentence. It is exact now; scrubbing keeps the tolerance it wants.
+
 ### Added
 
 - Listening and dictation practice (听力 / 听写). A text with a narration opens

Sources/HanReaderCore/Listening/DictationComparison.swift

@@ -152,6 +152,16 @@ public struct DictationResult: Hashable, Sendable {
 /// for building this inside HanReader rather than using a general-purpose
 /// dictation tool — the readings are already here.
 public enum DictationComparison {
+    /// How many characters of this text count towards a score.
+    ///
+    /// Punctuation and spacing are not the exercise, so they are not in the
+    /// count — which is what lets a screen notice that an answer is as long
+    /// as the sentence without caring whether the learner's input method
+    /// inserted a comma.
+    public static func scorableCount(of text: String) -> Int {
+        scorable(text).count
+    }
+
     /// Compares an attempt against the expected text.
     ///
     /// - Parameter readings: consulted only for characters that did not

Sources/HanReaderPlatform/ChineseInput.swift

@@ -0,0 +1,47 @@
+// HanReader — MIT licensed. See LICENSE.
+
+#if os(macOS)
+    import AppKit
+#endif
+
+/// Asking the system for a Chinese input source while a field is being typed
+/// into.
+///
+/// Listening practice is the one screen in the app where every keystroke is
+/// meant to be Chinese. Leaving the learner to switch input source themselves
+/// means doing it on the way in and again on the way out, every sentence, and
+/// discovering they forgot only once the answer has been typed in Latin
+/// letters and marked wrong.
+///
+/// ### Asking, not forcing
+///
+/// `allowedInputSourceLocales` is a *request*: the system honours it when the
+/// learner has a matching input source installed, and does nothing when they
+/// have not. That is the right shape — an app that could force an input
+/// source could also strand somebody with no way to type their own language —
+/// and it is why this reports nothing back. There is no failure here to
+/// handle, only a preference the system may or may not act on.
+public enum ChineseInput {
+    /// The locale to prefer. Simplified, matching the dictionary the app
+    /// bundles and the transcripts it is built for.
+    public static let locale = "zh-Hans"
+
+    /// Prefers a Chinese input source for whatever is being typed into now.
+    ///
+    /// Call it as the writing field takes focus. The preference belongs to
+    /// the focused field's input context, so it lasts as long as that field
+    /// is first responder and the system restores the learner's own choice
+    /// afterwards.
+    public static func prefer() {
+        #if os(macOS)
+            NSTextInputContext.current?.allowedInputSourceLocales = [locale]
+        #endif
+    }
+
+    /// Gives the choice back, for a field that is no longer the exercise.
+    public static func clearPreference() {
+        #if os(macOS)
+            NSTextInputContext.current?.allowedInputSourceLocales = nil
+        #endif
+    }
+}

Sources/HanReaderPlayback/AudioEngine.swift

@@ -24,7 +24,10 @@ public protocol AudioEngine: AnyObject {
     func load(_ url: URL)
     func play()
     func pause()
-    func seek(to time: Double)
+    /// - Parameter exactly: land on the requested time rather than wherever
+    ///   is cheap. Scrubbing a narration does not care; starting a phrase
+    ///   does, because the target *is* the first syllable.
+    func seek(to time: Double, exactly: Bool)
     /// Applied immediately when playing, and remembered for the next `play()`
     /// when not.
     func setRate(_ rate: Double)
@@ -173,13 +176,16 @@ final class AVPlayerAudioEngine: AudioEngine {
         player.pause()
     }
 
-    func seek(to time: Double) {
+    func seek(to time: Double, exactly: Bool) {
         let target = CMTime(seconds: max(0, time), preferredTimescale: 600)
-        // A tolerance, deliberately. The prototype seeked with
-        // `toleranceBefore: .zero, toleranceAfter: .zero`, which forces a
-        // frame-accurate seek — expensive, and pointless for spoken audio
-        // where a tenth of a second is inaudible.
-        let tolerance = CMTime(seconds: 0.1, preferredTimescale: 600)
+        // A tenth of a second is inaudible when the reader is dragging a
+        // scrubber through a narration, and a frame-accurate seek there is
+        // expensive for nothing. It is *not* inaudible at the start of a
+        // phrase: that target is the first syllable, AVPlayer resolves a
+        // tolerance by landing on whichever sync sample is cheapest — in
+        // practice an earlier one — and the reader hears the sentence
+        // begin mid-word.
+        let tolerance = exactly ? .zero : CMTime(seconds: 0.1, preferredTimescale: 600)
         player.seek(to: target, toleranceBefore: tolerance, toleranceAfter: tolerance)
     }
 

Sources/HanReaderPlayback/PlaybackModel+Phrase.swift

@@ -12,15 +12,26 @@ extension PlaybackModel {
     // MARK: - One phrase at a time
 
     /// Plays a single phrase, stopping exactly at its end.
+    /// Plays a single phrase, stopping exactly at its end.
+    ///
+    /// Asking for the phrase that is already loaded picks it up where it
+    /// stopped, a little way back, rather than starting it again — the
+    /// difference between pausing to think halfway through a long sentence
+    /// and never getting to the end of one.
     public func play(segment range: Range<Double>, drill: Drill? = nil) {
         guard state == .ready else { return }
+        let resuming = segment == range && !isPlaying
         cancelDrill()
         if let drill {
             self.drill = drill
         }
         segment = range
-        repeatsPlayed = 0
-        playSegmentOnce()
+        if resuming {
+            resumeSegment()
+        } else {
+            repeatsPlayed = 0
+            playSegmentOnce()
+        }
     }
 
     /// Goes back to playing the whole recording.
@@ -31,13 +42,39 @@ extension PlaybackModel {
         onStateChange?()
     }
 
+    /// How far back a resumed phrase rewinds.
+    ///
+    /// Picking up exactly where the sound stopped drops the listener into
+    /// the middle of a word with no run-up, and starting the phrase again
+    /// makes a long sentence impossible to finish — pause once near the end
+    /// and you are back at the beginning. Podcasts solves it with a short
+    /// rewind, and so does this.
+    public static let resumeRewind = 2.0
+
     func playSegmentOnce() {
+        play(segment: segment, from: nil)
+    }
+
+    /// Picks the phrase up again from a little before where it stopped.
+    func resumeSegment() {
+        guard let segment else { return }
+        let from = max(segment.lowerBound, playhead - Self.resumeRewind)
+        // Close enough to the start that a rewind would land there anyway,
+        // or past the end after a finished pass: begin the phrase again.
+        let isNearlyOver = playhead >= segment.upperBound - 0.05
+        play(segment: segment, from: isNearlyOver ? nil : from)
+    }
+
+    private func play(segment: Range<Double>?, from: Double?) {
         guard let segment, state == .ready else { return }
         activateSession()
         engine.setStopTime(segment.upperBound)
-        engine.seek(to: segment.lowerBound)
-        playhead = segment.lowerBound
-        observedTime = segment.lowerBound
+        let start = from ?? segment.lowerBound
+        // Exactly, because the target is the first syllable. A tolerance
+        // here is what makes a sentence begin mid-word.
+        engine.seek(to: start, exactly: true)
+        playhead = start
+        observedTime = start
         engine.play()
         isPlaying = true
         clearPauseReasons()

Sources/HanReaderPlayback/PlaybackModel.swift

@@ -219,7 +219,7 @@ public final class PlaybackModel {
         playhead = start
         observedTime = start
         if start > 0 {
-            engine.seek(to: start)
+            engine.seek(to: start, exactly: false)
         }
         engine.setRate(rate.rawValue)
         onStateChange?()
@@ -322,7 +322,7 @@ public final class PlaybackModel {
             self.segment = nil
             engine.setStopTime(nil)
         }
-        engine.seek(to: target)
+        engine.seek(to: target, exactly: segment != nil)
         playhead = target
         // Published immediately rather than left to the next report, or the
         // thumb springs back to where it was for a quarter of a second.

Sources/HanReaderUI/Models/PracticeModel+Flow.swift

@@ -0,0 +1,95 @@
+// HanReader — MIT licensed. See LICENSE.
+
+import Foundation
+import HanReaderCore
+import HanReaderPlayback
+
+/// Practising without pressing anything.
+///
+/// The screen this grew out of asked for four deliberate actions per
+/// sentence: play, check, grade, next. Three of them are inferable. A
+/// learner has finished an answer when it is as long as the sentence; an
+/// answer they heard correctly needs nothing said about it; and arriving at
+/// a phrase means they want to hear it. What is left is typing, which is the
+/// exercise.
+///
+/// Nothing here removes a control — the transport, Check and the grades are
+/// all still there for the cases the inference gets wrong. They stop being
+/// the way through.
+extension PracticeModel {
+    /// How long a passed phrase stays on screen before the next one.
+    ///
+    /// Long enough to read "8 of 8 correct" and see the marking, short
+    /// enough that it does not feel like waiting. Moving on instantly would
+    /// take the result away before it had been seen, which is the one piece
+    /// of feedback the exercise exists to give.
+    static let passPause = 1.2
+
+    /// Whether the answer is as long as the sentence.
+    ///
+    /// The signal that a learner has finished. Counting the characters that
+    /// will be scored rather than every character typed, so an input method
+    /// inserting its own punctuation does not hold the check back — and a
+    /// half-finished Pinyin syllable sitting in the IME's composition
+    /// buffer is not in the field yet, so it cannot trigger one either.
+    var isAnswerComplete: Bool {
+        let expected = DictationComparison.scorableCount(of: text)
+        return expected > 0 && DictationComparison.scorableCount(of: typed) >= expected
+    }
+
+    /// Called whenever the writing field changes.
+    ///
+    /// Checks as soon as the answer is long enough, and — if it was right —
+    /// moves on by itself. A learner who typed the sentence correctly has
+    /// said everything there is to say about it.
+    func answerChanged() async {
+        // `!isRevealed` covers an answer already marked as well as one the
+        // reader gave up on: checking always reveals, so a phrase with a
+        // result behind it is a revealed phrase.
+        guard phase == .ready, !isRevealed, isAnswerComplete else { return }
+        let phrase = current
+        await check()
+        guard current == phrase, let result else { return }
+        if result.listeningAccuracy >= 1 {
+            await advanceAfterPass(from: phrase)
+        }
+    }
+
+    /// Moves on from a phrase that was answered correctly.
+    private func advanceAfterPass(from phrase: Int) async {
+        advanceTask?.cancel()
+        advanceTask = Task { [weak self] in
+            await self?.wait(Self.passPause)
+            guard let self, !Task.isCancelled, current == phrase else { return }
+            // Only if they have not moved themselves in the meantime. The
+            // end of the list needs no guard of its own: `advance` clamps,
+            // so the last phrase stays where it is.
+            advance(by: 1)
+            advanceTask = nil
+        }
+    }
+
+    /// Waits for a pending move to land, so a test asserts where the reader
+    /// ended up rather than racing it.
+    func awaitPendingAdvance() async {
+        await advanceTask?.value
+    }
+
+    /// Stops a pending move, for a learner who did something else first.
+    func cancelAdvance() {
+        advanceTask?.cancel()
+        advanceTask = nil
+    }
+
+    /// Plays the phrase the reader has just arrived at.
+    ///
+    /// The whole screen is "listen, then write", so arriving at a phrase and
+    /// having to ask for the sound is a step that is never not wanted. Held
+    /// back while the boundary editor is open, where arriving somewhere is
+    /// a drag rather than a decision to practise, and while tapping along,
+    /// which is already playing the whole recording.
+    func playOnArrival() {
+        guard phase == .ready, !isEditing, tapping == nil, result == nil else { return }
+        play()
+    }
+}

Sources/HanReaderUI/Models/PracticeModel.swift

@@ -61,6 +61,13 @@ final class PracticeModel {
     var current = 0
     /// The last check, or nil if this phrase has not been answered yet.
     private(set) var result: DictationResult?
+    /// What the characters in the last check sound like.
+    ///
+    /// Kept from the check rather than looked up again by the view: the
+    /// lookup has already happened — marking a homophone is what it is for —
+    /// and a view that fetches is a view that cannot be rendered from a
+    /// value.
+    private(set) var readings: [Character: [CharacterReading]] = [:]
     /// Whether the transcript is on screen. Off until checked, because the
     /// answer being visible is the one thing that makes dictation worthless.
     private(set) var isRevealed = false
@@ -100,6 +107,13 @@ final class PracticeModel {
     /// files, and `private` in Swift reaches extensions in the *same* file
     /// only.
     var waveformTask: Task<Void, Never>?
+    /// A pending move to the next phrase after a correct answer.
+    var advanceTask: Task<Void, Never>?
+    /// How the flow waits, injectable so a test asserts order rather than
+    /// the clock — the lesson the drill's gap already taught.
+    var wait: @MainActor (Double) async -> Void = { seconds in
+        try? await Task.sleep(for: .seconds(seconds))
+    }
 
     init(textID: TextID, services: AppServices, playback: PlaybackModel) {
         self.textID = textID
@@ -148,6 +162,7 @@ final class PracticeModel {
         alignTask = nil
         waveformTask?.cancel()
         waveformTask = nil
+        cancelAdvance()
         // Through the same path the Stop button takes, rather than clearing
         // the flag here: dismissing the sheet part-way through tapping means
         // the same thing as stopping, and two ways to stop is two places to
@@ -205,9 +220,11 @@ final class PracticeModel {
 
     func select(_ index: Int) {
         guard phrases.contains(where: { $0.index == index }) else { return }
+        cancelAdvance()
         current = index
         typed = attempts[index]?.typed ?? ""
         result = nil
+        readings = [:]
         // Hidden again — unless the boundary editor is open, which shows
         // the phrase's text because a boundary cannot be placed without
         // knowing which words it is meant to contain. Leaving the flag
@@ -271,6 +288,7 @@ final class PracticeModel {
             readings: { readings[$0] ?? [] },
         )
         result = outcome
+        self.readings = readings
         isRevealed = true
         // A reader who showed the answer and then copied it has not
         // demonstrated anything about their listening, and recording a pass