feat: add AI voice transcription fallback for domestic Android ROMs

2026-09-15 22:02:26 +08:00
parent 670260f8e2
commit 35b493e652
8 changed files with 683 additions and 90 deletions
@@ -1,3 +1,4 @@
+import 'dart:io';
 import 'dart:convert';

 import 'package:flutter_secure_storage/flutter_secure_storage.dart';
@@ -84,6 +85,127 @@ class AiService {
    return Uri.tryParse('$base/v1/chat/completions');
  }

+  static Uri? resolveChatCompletionsUri({
+    required AiProviderType provider,
+    required String endpoint,
+    required String model,
+  }) {
+    final base = endpoint.trim().replaceFirst(RegExp(r'/+$'), '');
+    if (base.isEmpty) return null;
+    if (provider == AiProviderType.gemini) {
+      if (base.contains(':generateContent')) {
+        return Uri.tryParse(base);
+      }
+      return Uri.tryParse('$base/models/$model:generateContent');
+    }
+    if (base.endsWith('/responses')) {
+      final root = base.substring(0, base.length - '/responses'.length);
+      return Uri.tryParse('$root/chat/completions');
+    }
+    if (base.endsWith('/chat/completions')) {
+      return Uri.tryParse(base);
+    }
+    if (base.endsWith('/v1')) {
+      return Uri.tryParse('$base/chat/completions');
+    }
+    return Uri.tryParse('$base/v1/chat/completions');
+  }
+
+  /// Transcribes spoken audio file to English text using the configured AI multimodal model.
+  Future<String?> transcribeAudio({
+    required String filePath,
+    required AiProviderType provider,
+    required String endpoint,
+    required String model,
+  }) async {
+    if (provider == AiProviderType.mock) return null;
+    final file = File(filePath);
+    if (!await file.exists()) return null;
+    final bytes = await file.readAsBytes();
+    if (bytes.isEmpty) return null;
+
+    final key = await resolveApiKey();
+    final uri = resolveChatCompletionsUri(
+      provider: provider,
+      endpoint: endpoint,
+      model: model,
+    );
+    if (key == null || key.isEmpty || uri == null) return null;
+
+    final ext = filePath.split('.').last.toLowerCase();
+    final format = (ext == 'wav' || ext == 'mp3' || ext == 'm4a' || ext == 'aac') ? ext : 'm4a';
+    final base64Data = base64Encode(bytes);
+
+    try {
+      if (provider == AiProviderType.gemini) {
+        final mimeType = format == 'wav' ? 'audio/wav' : (format == 'mp3' ? 'audio/mp3' : 'audio/mp4');
+        final response = await http.post(
+          uri,
+          headers: {'x-goog-api-key': key, 'Content-Type': 'application/json'},
+          body: jsonEncode({
+            'contents': [
+              {
+                'parts': [
+                  {
+                    'text': 'Transcribe the spoken English speech in this audio file accurately. Return ONLY the transcribed English words. If silence or unintelligible, output nothing.',
+                  },
+                  {
+                    'inline_data': {
+                      'mime_type': mimeType,
+                      'data': base64Data,
+                    }
+                  }
+                ]
+              }
+            ]
+          }),
+        ).timeout(const Duration(seconds: 25));
+        if (response.statusCode < 200 || response.statusCode >= 300) return null;
+        return _extractResponseContent(provider, response.body);
+      } else {
+        final response = await http.post(
+          uri,
+          headers: {
+            'Authorization': 'Bearer $key',
+            'Content-Type': 'application/json',
+          },
+          body: jsonEncode({
+            'model': model,
+            'messages': [
+              {
+                'role': 'user',
+                'content': [
+                  {
+                    'type': 'text',
+                    'text': 'Transcribe the spoken English speech in this audio file accurately. Output ONLY the raw transcribed English words without quotes, punctuation tags, or commentary. If silence or noise, return nothing.',
+                  },
+                  {
+                    'type': 'input_audio',
+                    'input_audio': {
+                      'data': base64Data,
+                      'format': format,
+                    },
+                  }
+                ],
+              }
+            ],
+            'temperature': 0.1,
+          }),
+        ).timeout(const Duration(seconds: 25));
+        if (response.statusCode < 200 || response.statusCode >= 300) return null;
+        final raw = _extractResponseContent(provider, response.body);
+        if (raw == null) return null;
+        var text = raw.trim();
+        if (text.startsWith('"') && text.endsWith('"') && text.length >= 2) {
+          text = text.substring(1, text.length - 1).trim();
+        }
+        return text;
+      }
+    } catch (_) {
+      return null;
+    }
+  }
+
  static Map<String, dynamic> _buildOpenAiPayload({
    required Uri uri,
    required String model,
@@ -57,6 +57,12 @@ class AppState extends ChangeNotifier {
  AiProviderType aiProvider = AiProviderType.mock;
  String aiEndpoint = '';
  String aiModel = '';
+
+  AiConfigFile get aiConfig => AiConfigFile(
+        provider: aiProvider,
+        endpoint: aiEndpoint,
+        model: aiModel,
+      );
  String? cachedAdaptiveLessonRaw;
  DateTime? cachedAdaptiveLessonAuditedAt;
  String? cachedAdaptiveLessonAuditor;
@@ -19,6 +19,9 @@ class VoiceService {
  bool _speechReady = false;
  bool _ttsInitialized = false;

+  void Function(String status)? _statusListener;
+  void Function(String error)? _errorListener;
+
  Future<void> _initTts() async {
    if (_ttsInitialized) return;
    try {
@@ -65,6 +68,8 @@ class VoiceService {
    } catch (_) {}
  }

+  Future<bool> hasRecordPermission() => _recorder.hasPermission();
+
  Future<bool> startRecording() async {
    if (!await _recorder.hasPermission()) return false;
    final directory = await getApplicationDocumentsDirectory();
@@ -125,27 +130,70 @@ class VoiceService {
    await _player.dispose();
  }

-  Future<bool> initializeSpeech() async {
-    _speechReady = await _stt.initialize();
+  Future<bool> initializeSpeech({
+    void Function(String status)? onStatus,
+    void Function(String error)? onError,
+  }) async {
+    _statusListener = onStatus;
+    _errorListener = onError;
+    try {
+      _speechReady = await _stt.initialize(
+        onError: (val) {
+          _errorListener?.call(val.errorMsg);
+        },
+        onStatus: (val) {
+          _statusListener?.call(val);
+        },
+        debugLogging: false,
+      );
      return _speechReady;
+    } catch (_) {
+      _speechReady = false;
+      return false;
+    }
  }

  Future<bool> startListening(
-    void Function(String text, bool finalResult) onResult,
-  ) async {
-    if (!_speechReady && !await initializeSpeech()) {
-      return false;
+    void Function(String text, bool finalResult) onResult, {
+    void Function(String status)? onStatus,
+    void Function(String error)? onError,
+  }) async {
+    _statusListener = onStatus;
+    _errorListener = onError;
+    try {
+      if (!_speechReady || !_stt.isAvailable) {
+        final ready = await initializeSpeech(onStatus: onStatus, onError: onError);
+        if (!ready) return false;
      }
+
+      String? targetLocaleId = 'en_US';
+      try {
+        final locales = await _stt.locales();
+        if (locales.isNotEmpty) {
+          final enLocale = locales.firstWhere(
+            (l) => l.localeId.toLowerCase().startsWith('en'),
+            orElse: () => locales.first,
+          );
+          targetLocaleId = enLocale.localeId;
+        }
+      } catch (_) {}
+
      await _stt.listen(
        onResult: (result) =>
            onResult(result.recognizedWords, result.finalResult),
        listenOptions: SpeechListenOptions(
-        localeId: 'en_US',
+          localeId: targetLocaleId,
          listenFor: const Duration(seconds: 30),
          pauseFor: const Duration(seconds: 4),
+          partialResults: true,
+          cancelOnError: false,
        ),
      );
-    return true;
+      return _stt.isListening;
+    } catch (e) {
+      if (onError != null) onError(e.toString());
+      return false;
+    }
  }

  Future<void> stopListening() => _stt.stop();
@@ -1,3 +1,4 @@
+import '../../core/ai_service.dart';
 import 'package:flutter/material.dart';

 import '../../core/app_state.dart';
@@ -32,10 +33,11 @@ class _AssessmentPreparationPageState extends State<AssessmentPreparationPage> {

  Future<void> _checkMicrophone() async {
    setState(() => checkingMicrophone = true);
-    final ready = await VoiceService.instance.initializeSpeech();
+    final sttReady = await VoiceService.instance.initializeSpeech();
+    final recReady = await VoiceService.instance.hasRecordPermission();
    if (!mounted) return;
    setState(() {
-      microphoneReady = ready;
+      microphoneReady = sttReady || recReady;
      checkingMicrophone = false;
    });
  }
@@ -135,6 +137,8 @@ class _AssessmentPageState extends State<AssessmentPage> {
  bool transcriptEdited = false;
  String lastTranscript = '';
  bool listening = false;
+  bool transcribing = false;
+  bool aiVoiceRecording = false;
  bool audioPlayed = false;
  bool speakingUnavailable = false;
  AssessmentRecord? completedRecord;
@@ -166,31 +170,98 @@ class _AssessmentPageState extends State<AssessmentPage> {
  }

  Future<void> _mic() async {
+    if (aiVoiceRecording) {
+      final path = await VoiceService.instance.stopRecording();
+      if (!mounted) return;
+      setState(() {
+        aiVoiceRecording = false;
+        listening = false;
+        transcribing = true;
+      });
+      if (path != null) {
+        final config = widget.state.aiConfig;
+        final transcribed = await AiService.instance.transcribeAudio(
+          filePath: path,
+          provider: config.provider,
+          endpoint: config.endpoint,
+          model: config.model,
+        );
+        if (mounted) {
+          setState(() {
+            transcribing = false;
+            if (transcribed != null && transcribed.trim().isNotEmpty) {
+              controller.text = transcribed.trim();
+              usedMic = true;
+              lastTranscript = transcribed.trim();
+              transcriptEdited = false;
+              speakingUnavailable = false;
+            }
+          });
+          if (transcribed == null || transcribed.trim().isEmpty) {
+            ScaffoldMessenger.of(context).showSnackBar(
+              const SnackBar(content: Text('未识别到清晰语音，请再试一次。')),
+            );
+          }
+        }
+      } else {
+        if (mounted) setState(() => transcribing = false);
+      }
+      return;
+    }
+
    if (listening) {
      await VoiceService.instance.stopListening();
      if (mounted) setState(() => listening = false);
      return;
    }
-    final ready = await VoiceService.instance.startListening((text, _) {
+    final ready = await VoiceService.instance.startListening(
+      (text, _) {
        if (mounted) {
          setState(() {
            controller.text = text;
            usedMic = true;
            lastTranscript = text;
+            transcriptEdited = false;
          });
        }
+      },
+      onStatus: (status) {
+        if (mounted && (status == 'notListening' || status == 'done')) {
+          setState(() => listening = false);
+        }
+      },
+      onError: (err) {
+        if (mounted) {
+          setState(() => listening = false);
+        }
+      },
+    );
+    if (!ready) {
+      final recordStarted = await VoiceService.instance.startRecording();
+      if (mounted) {
+        setState(() {
+          aiVoiceRecording = recordStarted;
+          listening = recordStarted;
+          speakingUnavailable = !recordStarted;
        });
+        if (recordStarted) {
+          ScaffoldMessenger.of(context).showSnackBar(
+            const SnackBar(content: Text('已启动麦克风录音，回答后再次点击，AI 将自动转写为英文。')),
+          );
+        } else {
+          ScaffoldMessenger.of(context).showSnackBar(
+            const SnackBar(content: Text('无法访问麦克风，口语可稍后补测。')),
+          );
+        }
+      }
+      return;
+    }
    if (mounted) {
      setState(() {
        listening = ready;
        speakingUnavailable = !ready;
      });
    }
-    if (!ready && mounted) {
-      ScaffoldMessenger.of(context).showSnackBar(
-        const SnackBar(content: Text('语音识别不可用；口语可稍后补测，不会判为语言错误。')),
-      );
-    }
  }

  bool _openCorrect() {
@@ -409,8 +480,10 @@ class _AssessmentPageState extends State<AssessmentPage> {
            ),
            if (task.skill == AssessmentSkill.speaking)
              SecondaryButton(
-                label: listening ? '停止录音' : '使用麦克风回答',
-                onPressed: _mic,
+                label: transcribing
+                    ? '正在 AI 识别…'
+                    : (listening ? '停止录音并识别' : '使用麦克风回答'),
+                onPressed: transcribing ? null : _mic,
              ),
            if (task.skill == AssessmentSkill.speaking && speakingUnavailable)
              SecondaryButton(
@@ -113,6 +113,8 @@ class _DialoguePageState extends State<DialoguePage> {
  String? hint;
  bool listening = false;
  bool recording = false;
+  bool transcribing = false;
+  bool aiVoiceRecording = false;
  bool playingRecording = false;
  bool usedVoice = false;
  bool transcriptEdited = false;
@@ -368,12 +370,52 @@ class _DialoguePageState extends State<DialoguePage> {
  }

  Future<void> _toggleListening() async {
+    if (aiVoiceRecording) {
+      final path = await VoiceService.instance.stopRecording();
+      if (!mounted) return;
+      setState(() {
+        aiVoiceRecording = false;
+        listening = false;
+        transcribing = true;
+      });
+      if (path != null) {
+        final config = widget.state.aiConfig;
+        final transcribed = await AiService.instance.transcribeAudio(
+          filePath: path,
+          provider: config.provider,
+          endpoint: config.endpoint,
+          model: config.model,
+        );
+        if (mounted) {
+          setState(() {
+            transcribing = false;
+            if (transcribed != null && transcribed.trim().isNotEmpty) {
+              controller.text = transcribed.trim();
+              usedVoice = true;
+              lastTranscript = transcribed.trim();
+              transcriptEdited = false;
+            }
+          });
+          if (transcribed == null || transcribed.trim().isEmpty) {
+            ScaffoldMessenger.of(context).showSnackBar(
+              const SnackBar(content: Text('未识别到清晰语音，请再试一次或使用键盘输入。')),
+            );
+          }
+        }
+      } else {
+        if (mounted) setState(() => transcribing = false);
+      }
+      return;
+    }
+
    if (listening) {
      await VoiceService.instance.stopListening();
      if (mounted) setState(() => listening = false);
      return;
    }
-    final available = await VoiceService.instance.startListening((text, _) {
+
+    final available = await VoiceService.instance.startListening(
+      (text, _) {
        if (!mounted) return;
        setState(() {
          controller.text = text;
@@ -381,14 +423,41 @@ class _DialoguePageState extends State<DialoguePage> {
          lastTranscript = text;
          transcriptEdited = false;
        });
+      },
+      onStatus: (status) {
+        if (mounted && (status == 'notListening' || status == 'done')) {
+          setState(() => listening = false);
+        }
+      },
+      onError: (err) {
+        if (mounted) {
+          setState(() => listening = false);
+        }
+      },
+    );
+
+    if (!available) {
+      final recordStarted = await VoiceService.instance.startRecording();
+      if (mounted) {
+        setState(() {
+          aiVoiceRecording = recordStarted;
+          listening = recordStarted;
        });
+        if (recordStarted) {
+          ScaffoldMessenger.of(context).showSnackBar(
+            const SnackBar(content: Text('已启动麦克风录音，说完后再次点击麦克风，AI 将自动转写英文。')),
+          );
+        } else {
+          ScaffoldMessenger.of(context).showSnackBar(
+            const SnackBar(content: Text('无法访问麦克风，请检查手机录音权限。')),
+          );
+        }
+      }
+      return;
+    }
+
    if (!mounted) return;
    setState(() => listening = available);
-    if (!available) {
-      ScaffoldMessenger.of(
-        context,
-      ).showSnackBar(const SnackBar(content: Text('语音识别不可用；你仍可使用文字输入。')));
-    }
  }

  Future<void> _toggleRecording() async {
@@ -572,11 +641,22 @@ class _DialoguePageState extends State<DialoguePage> {
                filled: true,
                fillColor: AppColors.surface,
                prefixIcon: IconButton(
-                  tooltip: listening ? '停止录音' : '语音输入',
-                  icon: Icon(
-                    listening ? Icons.stop_circle_outlined : Icons.mic_none,
+                  tooltip: transcribing
+                      ? '正在 AI 识别…'
+                      : (listening ? '停止录音并识别' : '语音输入'),
+                  icon: transcribing
+                      ? const SizedBox(
+                          width: 18,
+                          height: 18,
+                          child: CircularProgressIndicator(strokeWidth: 2),
+                        )
+                      : Icon(
+                          listening
+                              ? Icons.stop_circle
+                              : Icons.mic_none,
+                          color: listening ? Colors.redAccent : null,
                        ),
-                  onPressed: _toggleListening,
+                  onPressed: transcribing ? null : _toggleListening,
                ),
                suffixIcon: IconButton(
                  icon: const Icon(Icons.send),
@@ -147,6 +147,7 @@ class _LessonFlowState extends State<LessonFlow> {
        content = _DialoguePendingStep(onOpenDialogue: widget.onOpenDialogue);
      case LessonStep.independent:
        content = _IndependentStep(
+          state: widget.state,
          segmentId: segment.id,
          keepRecording: widget.state.keepRecordings,
          activity: activity,
@@ -438,6 +439,8 @@ class _SpeakingStep extends StatefulWidget {
 class _SpeakingStepState extends State<_SpeakingStep> {
  bool listening = false;
  bool recording = false;
+  bool transcribing = false;
+  bool aiVoiceRecording = false;
  bool playingRecording = false;
  String transcript = '';
  String? recordingPath;
@@ -452,14 +455,83 @@ class _SpeakingStepState extends State<_SpeakingStep> {
  }

  Future<void> _toggleMic() async {
+    if (aiVoiceRecording) {
+      final path = await VoiceService.instance.stopRecording();
+      if (!mounted) return;
+      setState(() {
+        aiVoiceRecording = false;
+        listening = false;
+        transcribing = true;
+      });
+      if (path != null) {
+        final config = widget.state.aiConfig;
+        final text = await AiService.instance.transcribeAudio(
+          filePath: path,
+          provider: config.provider,
+          endpoint: config.endpoint,
+          model: config.model,
+        );
+        if (mounted) {
+          setState(() {
+            transcribing = false;
+            if (text != null && text.trim().isNotEmpty) {
+              transcript = text.trim();
+            }
+          });
+          if (text == null || text.trim().isEmpty) {
+            ScaffoldMessenger.of(context).showSnackBar(
+              const SnackBar(content: Text('未识别到清晰声音，请重试或点击“播放示范音”。')),
+            );
+          }
+        }
+      } else {
+        if (mounted) setState(() => transcribing = false);
+      }
+      return;
+    }
+
    if (listening) {
      await VoiceService.instance.stopListening();
      if (mounted) setState(() => listening = false);
      return;
    }
-    final ready = await VoiceService.instance.startListening((text, _) {
+
+    final ready = await VoiceService.instance.startListening(
+      (text, _) {
        if (mounted) setState(() => transcript = text);
+      },
+      onStatus: (status) {
+        if (mounted && (status == 'notListening' || status == 'done')) {
+          setState(() => listening = false);
+        }
+      },
+      onError: (err) {
+        if (mounted) {
+          setState(() => listening = false);
+        }
+      },
+    );
+
+    if (!ready) {
+      final recordStarted = await VoiceService.instance.startRecording();
+      if (mounted) {
+        setState(() {
+          aiVoiceRecording = recordStarted;
+          listening = recordStarted;
        });
+        if (recordStarted) {
+          ScaffoldMessenger.of(context).showSnackBar(
+            const SnackBar(content: Text('已启动麦克风录音，跟读完成后再次点击，AI 将自动转写发音。')),
+          );
+        } else {
+          ScaffoldMessenger.of(context).showSnackBar(
+            const SnackBar(content: Text('无法访问麦克风，请检查手机录音权限。')),
+          );
+        }
+      }
+      return;
+    }
+
    if (mounted) setState(() => listening = ready);
  }

@@ -526,8 +598,10 @@ class _SpeakingStepState extends State<_SpeakingStep> {
          ),
        ),
        SecondaryButton(
-          label: listening ? '停止录音' : '使用麦克风跟读',
-          onPressed: _toggleMic,
+          label: transcribing
+              ? '正在 AI 识别发音…'
+              : (listening ? '停止录音并识别' : '使用麦克风跟读'),
+          onPressed: transcribing ? null : _toggleMic,
        ),
        SecondaryButton(
          label: recording ? '停止本机录音' : '录音后回听',
@@ -871,6 +945,7 @@ class _DialoguePendingStep extends StatelessWidget {

 class _IndependentStep extends StatefulWidget {
  const _IndependentStep({
+    required this.state,
    required this.segmentId,
    required this.keepRecording,
    required this.activity,
@@ -883,6 +958,7 @@ class _IndependentStep extends StatefulWidget {
    required this.onContinue,
    required this.onLater,
  });
+  final AppState state;
  final LessonActivity activity;
  final String segmentId;
  final bool keepRecording;
@@ -902,6 +978,8 @@ class _IndependentStep extends StatefulWidget {
 class _IndependentStepState extends State<_IndependentStep> {
  bool listening = false;
  bool recording = false;
+  bool transcribing = false;
+  bool aiVoiceRecording = false;
  bool playingRecording = false;
  bool usedVoice = false;
  bool transcriptEdited = false;
@@ -968,12 +1046,53 @@ class _IndependentStepState extends State<_IndependentStep> {
  }

  Future<void> _toggleMic() async {
+    if (aiVoiceRecording) {
+      final path = await VoiceService.instance.stopRecording();
+      if (!mounted) return;
+      setState(() {
+        aiVoiceRecording = false;
+        listening = false;
+        transcribing = true;
+      });
+      if (path != null) {
+        final config = widget.state.aiConfig;
+        final text = await AiService.instance.transcribeAudio(
+          filePath: path,
+          provider: config.provider,
+          endpoint: config.endpoint,
+          model: config.model,
+        );
+        if (mounted) {
+          setState(() {
+            transcribing = false;
+            if (text != null && text.trim().isNotEmpty) {
+              widget.controller.text = text.trim();
+              usedVoice = true;
+              lastTranscript = text.trim();
+              transcriptEdited = false;
+            }
+          });
+          widget.onChanged();
+          if (text == null || text.trim().isEmpty) {
+            ScaffoldMessenger.of(context).showSnackBar(
+              const SnackBar(content: Text('未识别到声音，请重试或直接打字输入。')),
+            );
+          }
+        }
+      } else {
+        if (mounted) setState(() => transcribing = false);
+      }
+      return;
+    }
+
    if (listening) {
      await VoiceService.instance.stopListening();
      if (mounted) setState(() => listening = false);
      return;
    }
-    final ready = await VoiceService.instance.startListening((text, _) {
+
+    final ready = await VoiceService.instance.startListening(
+      (text, _) {
        if (!mounted) return;
        setState(() {
          widget.controller.text = text;
@@ -982,13 +1101,40 @@ class _IndependentStepState extends State<_IndependentStep> {
          transcriptEdited = false;
        });
        widget.onChanged();
-    });
-    if (mounted) setState(() => listening = ready);
-    if (!ready && mounted) {
-      ScaffoldMessenger.of(
-        context,
-      ).showSnackBar(const SnackBar(content: Text('语音识别不可用；你仍可输入英文完成写作练习。')));
+      },
+      onStatus: (status) {
+        if (mounted && (status == 'notListening' || status == 'done')) {
+          setState(() => listening = false);
        }
+      },
+      onError: (err) {
+        if (mounted) {
+          setState(() => listening = false);
+        }
+      },
+    );
+
+    if (!ready) {
+      final recordStarted = await VoiceService.instance.startRecording();
+      if (mounted) {
+        setState(() {
+          aiVoiceRecording = recordStarted;
+          listening = recordStarted;
+        });
+        if (recordStarted) {
+          ScaffoldMessenger.of(context).showSnackBar(
+            const SnackBar(content: Text('已启动麦克风录音，说完后再次点击，AI 将自动转写为英文。')),
+          );
+        } else {
+          ScaffoldMessenger.of(context).showSnackBar(
+            const SnackBar(content: Text('无法访问麦克风，请检查手机录音权限。')),
+          );
+        }
+      }
+      return;
+    }
+
+    if (mounted) setState(() => listening = ready);
  }

  @override
@@ -309,6 +309,8 @@ class _AdaptiveLessonPageState extends State<AdaptiveLessonPage> {
  bool showReference = false;
  String? answerFeedback;
  bool listening = false;
+  bool transcribing = false;
+  bool aiVoiceRecording = false;
  bool usedVoice = false;
  bool transcriptEdited = false;
  bool transcriptConfirmed = false;
@@ -413,12 +415,55 @@ class _AdaptiveLessonPageState extends State<AdaptiveLessonPage> {
  }

  Future<void> _toggleListening() async {
+    if (aiVoiceRecording) {
+      final path = await VoiceService.instance.stopRecording();
+      if (!mounted) return;
+      setState(() {
+        aiVoiceRecording = false;
+        listening = false;
+        transcribing = true;
+      });
+      if (path != null) {
+        final config = widget.state.aiConfig;
+        final transcribed = await AiService.instance.transcribeAudio(
+          filePath: path,
+          provider: config.provider,
+          endpoint: config.endpoint,
+          model: config.model,
+        );
+        if (mounted) {
+          setState(() {
+            transcribing = false;
+            if (transcribed != null && transcribed.trim().isNotEmpty) {
+              controller.text = transcribed.trim();
+              usedVoice = true;
+              transcriptEdited = false;
+              transcriptConfirmed = false;
+              lastTranscript = transcribed.trim();
+            }
+          });
+          final lesson = widget.state.cachedAdaptiveLesson;
+          if (lesson != null) _saveDraft(lesson);
+          if (transcribed == null || transcribed.trim().isEmpty) {
+            ScaffoldMessenger.of(context).showSnackBar(
+              const SnackBar(content: Text('未识别到清晰语音，请再试一次或输入文本。')),
+            );
+          }
+        }
+      } else {
+        if (mounted) setState(() => transcribing = false);
+      }
+      return;
+    }
+
    if (listening) {
      await VoiceService.instance.stopListening();
      if (mounted) setState(() => listening = false);
      return;
    }
-    final ready = await VoiceService.instance.startListening((text, _) {
+
+    final ready = await VoiceService.instance.startListening(
+      (text, _) {
        if (!mounted) return;
        setState(() {
          controller.text = text;
@@ -429,14 +474,41 @@ class _AdaptiveLessonPageState extends State<AdaptiveLessonPage> {
        });
        final lesson = widget.state.cachedAdaptiveLesson;
        if (lesson != null) _saveDraft(lesson);
+      },
+      onStatus: (status) {
+        if (mounted && (status == 'notListening' || status == 'done')) {
+          setState(() => listening = false);
+        }
+      },
+      onError: (err) {
+        if (mounted) {
+          setState(() => listening = false);
+        }
+      },
+    );
+
+    if (!ready) {
+      final recordStarted = await VoiceService.instance.startRecording();
+      if (mounted) {
+        setState(() {
+          aiVoiceRecording = recordStarted;
+          listening = recordStarted;
        });
+        if (recordStarted) {
+          ScaffoldMessenger.of(context).showSnackBar(
+            const SnackBar(content: Text('已启动麦克风录音，说完后再次点击，AI 将自动转写为英文。')),
+          );
+        } else {
+          ScaffoldMessenger.of(context).showSnackBar(
+            const SnackBar(content: Text('无法访问麦克风，请检查录音权限。你仍可输入英文完成补练。')),
+          );
+        }
+      }
+      return;
+    }
+
    if (!mounted) return;
    setState(() => listening = ready);
-    if (!ready) {
-      ScaffoldMessenger.of(
-        context,
-      ).showSnackBar(const SnackBar(content: Text('语音识别不可用；你仍可输入英文完成补练。')));
-    }
  }

  Future<void> _toggleRecording() async {
@@ -590,10 +662,21 @@ class _AdaptiveLessonPageState extends State<AdaptiveLessonPage> {
              filled: true,
              fillColor: AppColors.surface,
              prefixIcon: IconButton(
-                tooltip: listening ? '停止语音输入' : '语音输入',
+                tooltip: transcribing
+                    ? '正在 AI 识别…'
+                    : (listening ? '停止录音并识别' : '语音输入'),
                onPressed: _toggleListening,
-                icon: Icon(
-                  listening ? Icons.stop_circle_outlined : Icons.mic_none,
+                icon: transcribing
+                    ? const SizedBox(
+                        width: 18,
+                        height: 18,
+                        child: CircularProgressIndicator(strokeWidth: 2),
+                      )
+                    : Icon(
+                        listening
+                            ? Icons.stop_circle_outlined
+                            : Icons.mic_none,
+                        color: listening ? AppColors.green : null,
                      ),
              ),
              border: OutlineInputBorder(),
@@ -0,0 +1,35 @@
+import 'dart:io';
+import 'package:flutter_test/flutter_test.dart';
+import 'package:kouyu_english/core/ai_service.dart';
+import 'package:kouyu_english/core/models.dart';
+
+void main() {
+  test('transcribeAudio with valid test audio file returns transcription', () async {
+    final ai = AiService.instance;
+    ai.setFallbackApiKey('sk-242EMNuXYjxSEktp91E8QqS8ejGs9XImrDddIA5JHXdeCKLSUcB91vrSmhyv45pf');
+
+    // Create a temporary wav file if not exists
+    final tempFile = File('/tmp/test_unit.wav');
+    if (!await tempFile.exists()) {
+      // 44-byte standard wav header with 1 second silence
+      final wavHeader = <int>[
+        0x52, 0x49, 0x46, 0x46, 0x24, 0x7d, 0x00, 0x00, 0x57, 0x41, 0x56, 0x45,
+        0x66, 0x6d, 0x74, 0x20, 0x10, 0x00, 0x00, 0x00, 0x01, 0x00, 0x01, 0x00,
+        0x80, 0x3e, 0x00, 0x00, 0x00, 0x7d, 0x00, 0x00, 0x02, 0x00, 0x10, 0x00,
+        0x64, 0x61, 0x74, 0x61, 0x00, 0x7d, 0x00, 0x00,
+      ];
+      final wavData = List<int>.filled(32000, 0);
+      await tempFile.writeAsBytes(wavHeader + wavData);
+    }
+
+    final result = await ai.transcribeAudio(
+      filePath: tempFile.path,
+      provider: AiProviderType.compatible,
+      endpoint: 'https://codex.slcydia.fun/v1/responses',
+      model: 'gemini-3.7-flash-high',
+    );
+
+    print('Transcribe result: $result');
+    expect(result, isNotNull);
+  });
+}