Response Handling

Server Response Format

Successful response (HTTP 200):

{
  "audio_url": "https://server.com/path/to/ai_response.wav",
  "ai_usage_in_seconds": 45.5,
  "conversation": { "...updated conversation history..." }
}

Response Processing Steps

URL Extraction: Extract audio_url from server response
Credit Update: If ai_usage_in_seconds present, round up and update local credits
Conversation Save: If conversation present, save to [CourseCode]_conversation.json
Download: Download AI response audio file from provided URL (timeout: 120 seconds)
Storage: Save to AppData/AI_Voice_Responses/response_[timestamp].wav
Playback: Use just_audio player to play the response
Replay Cache: Mark response as replayable for user to replay later
Cleanup: Files are cleaned up when widget is disposed OR when new recording starts

Error Handling

Scenario	User Message
No internet	“No internet connection” (recording blocked)
No credits	Shows “Credit Limit Reached” dialog with purchase option
Token failure	“Failed to connect to AI. You can try switching to other voices in General Settings, but it might result in fewer conversations.”
Server errors	“Failed to connect to AI. You can try switching to other voices in General Settings, but it might result in fewer conversations.”
Download failure	“Failed to download response”
Permission denied	Shows “Microphone Permission Required” dialog with settings button
Permanently denied	Opens system settings via `openAppSettings()`

File Storage Paths

Purpose	Path
Recording (temp)	`[temp]/voice_recording_[timestamp].wav`
AI Response	`AppData/AI_Voice_Responses/response_[timestamp].wav`
Conversation History	`AppData/JSONs/Conversations/[CourseCode]_conversation.json`
Audio Usage	`AppData/JSONs/User_Audio_Usage/[CourseCode]_Usage.json`
Journal Responses	`AppData/JSONs/User_Workbook_Responses/[CourseCode]1_response.json`
User Profile	`AppData/JSONs/user_profile.json`

Journal Response Collection

The _collectJournalResponses method:

Get application documents directory path
Search for files in User_Workbook_Responses directory with pattern: [CourseCode]1_response.json
Check if the expected file exists
If found, read and parse JSON, extract data field
Return structured object with has_journal flag and entries