🎙️ BisonNotes AI

AI-Powered Voice Recording, Transcription, and Summarization for Apple Platforms

---

🌟 Overview

SwiftUI app for recording audio, transcribing it with local or cloud engines, and generating summaries, tasks, and reminders. Ships on iOS, iPadOS, watchOS, and native macOS. Core Data powers persistence; background jobs handle long/complex processing; WatchConnectivity imports complete watch recordings back to the phone.

Your recordings can stay entirely on-device: Parakeet handles transcription locally and MLX Swift handles summarization locally, with cloud engines available only if you opt into them.

✨ Key Features

• 🎙️ Record Anywhere — iPhone, iPad, Apple Watch, and native Mac, with pause/resume, Control Center widget, and Action Button support
• ⌚️ Independent Watch Recorder — The watch records on its own and transfers complete files back to the phone, surviving offline, relaunch, and reconnect
• 🖥️ Native Mac Meeting Capture — Optional ScreenCaptureKit system-audio capture mixed with your microphone, with selectable inputs and stall/device-recovery monitoring
• 🔒 Fully On-Device Path — Parakeet transcription plus MLX Swift summarization run locally; no audio leaves the device unless you choose a cloud engine
• 🤖 Pluggable AI Engines — On-device (MLX Swift, llama.cpp legacy), Apple Foundation Models, OpenAI, OpenAI-compatible, Mistral AI, Google AI Studio, AWS Bedrock/Transcribe, Whisper, Wyoming, and Ollama
• 📝 Summaries, Tasks & Reminders — Structured extraction from transcripts, rendered with MarkdownUI
• 🔗 Import From Link — Direct audio/video files, transcript documents, and public YouTube captions
• ☁️ Guarded iCloud Sync — Per-recording Keep on This Device exclusions, durable deletion markers, and explicit review of older cloud-only items
• ♿️ Accessibility Throughout — VoiceOver, Voice Control, non-color status cues, Reduce Motion, Dynamic Type, and Full Keyboard Access

⚠️ Not HIPAA Compliant

BisonNotes AI is a personal productivity app. It is not HIPAA-compliant and we do not provide Business Associate Agreements (BAAs). Do not use it to record or process protected health information, and review the in-app notice before enabling iCloud sync.

Quick links: Full User Guide • v2.2 Release Guide (WordPress) • Accessibility Matrix • Mistral AI Free Setup • Regression Testing Regimen • Build & Test • Architecture

v2.2 Highlights

• The Mac app is now a native macOS app while retaining the same bundle identity, app container, Core Data store, and iCloud container used by the previous Catalyst build. It adds native windows, a dedicated Settings window, standard File/Edit commands, keyboard shortcuts, persistent archive bookmarks, AppKit sharing, and native RTF/PDF export.
• Native macOS now includes a Share extension for importing supported audio and transcript files from the Mac Share menu, plus small and medium desktop widgets that open BisonNotes and start a new recording.
• Native Mac recording uses selectable Core Audio inputs plus ScreenCaptureKit meeting-audio capture. It remembers the preferred microphone through temporary disconnects, monitors input-device changes, preserves microphone segments across a device recovery, validates microphone and system tracks independently, saves whichever usable track remains, and retains failed source media in Application Support for recovery.
• Enabling Record Meeting Audio now provides a guided Screen & System Audio Recording permission flow, including the required quit-and-reopen step. If Live Transcription is enabled, the finalized meeting recording is queued for file-based transcription so the combined audio is transcribed.
• Native macOS can run the Ternary Bonsai 27B MLX model on Macs with at least 16 GB RAM; the approximately 8.5 GB model remains excluded from iPhone and iPad.
• On-device Parakeet setup now recovers valid cached models more reliably, reports missing model assets accurately, and waits for model preparation to finish before starting transcription.
• Import from web links can now bring in direct audio/video files, transcript documents, and public YouTube captions, with a guided pasted-transcript recovery flow when YouTube blocks automated caption downloads.
• Web downloads are bounded by content type and size, use isolated sessions, validate redirects and final media before persistence, preserve server-provided filenames, and clean up temporary files when downstream import fails.
• Share imports now wait safely when another import is already running instead of deleting staged files, and caption cleanup removes one layer of HTML encoding without changing intentionally escaped text.
• Summary-only deletions now queue removal of both live and backup CloudKit records, including content-index cleanup, so an offline deletion can be completed when iCloud becomes available instead of restoring the deleted summary later.
• Thinking-capable MLX models keep their reasoning internal. Reasoning tags, partial traces, and prose preambles are stripped before summaries, tasks, reminders, and suggested titles are parsed or displayed.
• Common iPhone, iPad, Mac, and Apple Watch tasks now have explicit VoiceOver labels, values, hints, and non-color state cues across setup, recording, imports, recordings, playback, transcripts, summaries, settings, and watch recording.
• The custom audio scrubber remains visually unchanged but is exposed as an adjustable accessibility control with current/remaining time and 15-second seek increments.
• Recording, transcript, and summary rows expose contextual status such as duration, file size, archive/local audio, iCloud/local-only state, transcript availability, summary availability, task/reminder counts, and location availability.
• Apple Watch recording now exposes state for the main record/stop control, mute/pause, transfer progress, low battery, and error recovery, and the pulsing recording indicators respect Reduce Motion.
• A dedicated accessibility evidence set was added: docs/accessibility-matrix.md, docs/app-store-accessibility.md, docs/accessibility.html, and BisonNotes AI/BisonNotes AIUITests/BisonNotesAIAccessibilityTests.swift.

v2.1 Highlights

• iCloud sync now uses stronger guardrails: a HIPAA notice before enabling sync, per-recording Keep on This Device exclusions, deletion markers, active-manifest review for older cloud-only items, and clearer production CloudKit schema errors.
• Parakeet transcription recovery is more reliable. The app recognizes cached model files after app updates or settings resets, supports English v2 and multilingual v3 model choices, reports download/prepare progress more accurately, and avoids short final tail chunks during long on-device transcriptions.
• Recording reliability is improved through stricter audio session ownership, safer background processing interruption handling, crash-safe recording recovery, and conservative cleanup of stale temporary audio files.
• Release validation now has app/watch .xctestplan files, deterministic UI-test launch fixtures, focused iCloud and transcription regression tests, and a documented regression testing regimen.

v2.0 Foundation Highlights

• Modernized SwiftUI interface across Recordings, Transcripts, Summaries, Setup, and Settings, with denser action placement and cleaner status surfaces.
• Redesigned watchOS recorder around one large tap target: tap to record, tap to stop, and use mute to pause/resume the same file. Transfer status and low-battery warnings stay visible without crowding the primary action.
• On Device AI is now backed by MLX Swift by default on supported devices. New/legacy users with 4 GB+ RAM migrate to MLX automatically; devices below that fall back to Mistral AI.
• Legacy llama.cpp On-Device AI remains available for 6 GB+ devices, but the removed LFM 2.5 model is deleted during migration and no longer appears in model lists.
• Watch sync no longer uses live audio chunks or phone-side recording control. The watch records independently, sends the finished file via WCSession.transferFile, and receives queued completion/failure confirmations.

Architecture

• Data: Core Data model at BisonNotes AI/BisonNotes_AI.xcdatamodeld stores recordings, transcripts, summaries, and jobs. Sensitive credentials (API keys, AWS access keys, Bedrock session tokens) live in the iOS Keychain, never on disk in plaintext.
• Engines: Pluggable services for On Device transcription, OpenAI, OpenAI-compatible APIs, Mistral AI, Google AI Studio, AWS Bedrock/Transcribe, Whisper (REST), Wyoming streaming, Ollama, On Device AI (MLX Swift), On Device AI Legacy (llama.cpp), and Apple Native (Foundation Models). Each engine pairs a service with a settings view.
• Background: BackgroundProcessingManager coordinates queued work with retries, timeouts, and recovery. Large files are chunked and processed streaming‑first.
• Recording: A platform-aware audio pipeline — AVAudioRecorder on iOS/iPadOS and AVAudioEngine/AVAudioFile on native macOS (AudioRecorderViewModel+MacEngine.swift) — with shared Pause/Resume support, optional Mac meeting-audio capture through MacSystemAudioCapture, first-buffer and stall monitoring, independent track validation, recoverable PCM segments, and crash-safe interruption handling.
• Watch Sync: WatchConnectivityManager (on iOS and watch targets) manages reachability, complete-file transfers, duplicate protection, queued acknowledgments, and import recovery. Watch complications and a Control Center recording widget are bundled as separate targets.
• UI: SwiftUI views under Views/ implement recording, summaries, transcripts, setup, and settings. AI-generated content uses MarkdownUI for professional formatting. View models isolate state and side effects.

Project Structure

• BisonNotes AI/: shared iOS, iPadOS, and native macOS app source
  • Notable folders: Models/, Views/, ViewModels/, OpenAI/, AWS/, Wyoming/, WatchConnectivity/, OnDeviceLLM/, FluidAudio/, Services/
  • Assets: Assets.xcassets; config: Info.plist, .entitlements
  • Uses Xcode's file-system synchronized groups, so dropping new Swift files into these folders automatically adds them to the project—no manual .xcodeproj edits are necessary.
• BisonNotes Share/: iOS Share Extension target for importing audio from other apps
• BisonNotes Share macOS/: native macOS Share Extension target
• BisonNotes AI Watch App/: watchOS companion app
• BisonNotes Watch Widget/: Watch complications surface for live recording state
• BisonNotes AI Controls/: Control Center recording widget (Recording Control Widget)
• Tests: BisonNotes AITests/ (unit), BisonNotes AIUITests/ (UI), plus watch tests

Build and Test

• Open in Xcode: open "BisonNotes AI/BisonNotes AI.xcodeproj"
• Build (iOS): xcodebuild -project "BisonNotes AI/BisonNotes AI.xcodeproj" -scheme "BisonNotes AI" -configuration Debug build
• Test (iOS): xcodebuild test -project "BisonNotes AI/BisonNotes AI.xcodeproj" -scheme "BisonNotes AI" -destination 'platform=iOS Simulator,name=iPhone 15'
• Build (native macOS): xcodebuild -project "BisonNotes AI/BisonNotes AI.xcodeproj" -scheme "BisonNotes AI macOS" -destination 'platform=macOS' -configuration Debug build
• Archive (native macOS): xcodebuild archive -project "BisonNotes AI/BisonNotes AI.xcodeproj" -scheme "BisonNotes AI macOS" -destination 'generic/platform=macOS' -configuration Release
• Use the watch app scheme to run the watch target. SwiftPM resolves automatically in Xcode.
• Release validation should follow docs/testing-regimen.md, including app/watch test plans, native macOS coverage, and manual hardware checks for microphone/device switching, watch transfer, iCloud, Parakeet, share import, Control Center, Action Button, Mac meeting audio, archive restore, and long hidden-window processing.
• Accessibility validation should include the automated UI audit class: xcodebuild test -project "BisonNotes AI/BisonNotes AI.xcodeproj" -scheme "BisonNotes AI" -destination 'platform=iOS Simulator,name=iPhone 17 Pro' -only-testing:"BisonNotes AIUITests/BisonNotesAIAccessibilityTests"
• Real-device accessibility release checks are still required for VoiceOver, Voice Control, Switch Control sampling, Full Keyboard Access on iPad/macOS, largest Dynamic Type, light/dark contrast modes, Reduce Motion, Apple Watch VoiceOver, Control Center, and Action Button.
• See CLAUDE.md for native macOS build notes, the duplicate-library modulemap cleanup, and the retired AWS/Smithy Catalyst archive constraint.

Accessibility Development Notes

• Shared accessibility strings and modifiers live in BisonNotes AI/BisonNotes AI/AccessibilitySupport.swift. Prefer these helpers for duration/status strings, row labels, announcements, and custom card semantics instead of one-off labels.
• Stable automation identifiers live in BisonNotes AI/BisonNotes AI/AccessibilityIdentifiers.swift. Add identifiers only for surfaces needed by UI tests, audit navigation, or repeated external automation.
• Deterministic accessibility UI tests live in BisonNotes AI/BisonNotes AIUITests/BisonNotesAIAccessibilityTests.swift and use DEBUG launch arguments from UITestSupport.swift, including --show-first-setup.
• App Store accessibility evidence lives in docs/accessibility-matrix.md and docs/app-store-accessibility.md. Keep those files and the public docs/accessibility.html page aligned with implemented behavior before claiming Accessibility Nutrition Labels.
• The shared SwiftUI app surfaces carry over to native macOS, but the Mac release still needs manual VoiceOver, Full Keyboard Access, keyboard navigation, multi-window resizing, and real iCloud/file import validation.

Dependencies

The project uses Swift Package Manager for dependency management. Major dependencies include:

Cloud Services

• AWS SDK for Swift: Cloud transcription and AI processing
  • Requires compatible 1.x releases from 1.7.46; the former exact 1.6.113 pin was removed with Mac Catalyst because the Smithy build-tool staging collision required both native-macOS and Catalyst products in the same archive
  • AWSBedrock & AWSBedrockRuntime: Claude AI models (Claude 4.5 Haiku, Claude Sonnet 4.5, Llama 4 Maverick)
  • AWSTranscribe & AWSTranscribeStreaming: Speech-to-text
  • AWSS3: File storage and retrieval
  • AWSClientRuntime: Core AWS functionality

On-Device AI

• MLX Swift / MLX Swift LM: Backs the default On Device AI summarization path in v2.0.
  • Models: Ternary Bonsai 1.7B (~470 MB, 4 GB+ RAM), 4B (~1.1 GB, 6 GB+ RAM, default), and 8B (~2.3 GB, 8 GB+ RAM)
  • Native macOS also offers Ternary Bonsai 27B (~8.5 GB, 16 GB+ RAM); it is not available in the iOS model catalog
  • Models download from Hugging Face on first use and run locally after download
  • 4-6 GB devices use the 1.7B model; 6 GB+ devices default to the 4B model; 8 GB+ devices can select the 8B model
• llama.cpp: Embedded as a pre-compiled xcframework (Frameworks/llama.xcframework) for Metal-accelerated on-device LLM inference
  • GitHub: https://github.com/ggerganov/llama.cpp
  • Supports GGUF model format with Q4_K_M quantization (optimal for mobile)
  • Available models: Gemma 3n E4B/E2B, Granite 4.0 H Tiny/Micro, Ministral 3B, Qwen3.5 2B/4B
  • Legacy engine in v2.0; models require 6 GB+ RAM, with 8 GB+ for larger models
  • The native Mac target consumes the upstream macos-arm64_x86_64 slice directly; no locally patched Catalyst slice is required.

UI & Formatting

• MarkdownUI: Professional markdown rendering for AI-generated summaries, headers, lists, and formatted text

On-Device Transcription

• FluidAudio Parakeet: On-device transcription using NVIDIA Parakeet models.
  • Complete privacy - audio never leaves device
  • Works offline after model download
  • v2.1 supports Parakeet v2 (English) and Parakeet v3 (multilingual), keeps valid cached downloads across app updates/settings resets, and clears stale download state when model files are missing
  • WhisperKit was removed in v1.8; existing users are automatically migrated to Parakeet

Apple Frameworks

• WatchConnectivity: Syncing between iPhone and Apple Watch
• Core Data: Local data persistence
• AVFoundation: Audio recording and playback

All external dependencies are resolved automatically via Swift Package Manager when building in Xcode.

Local Dev Setup

• Requirements: macOS with Xcode (15+ recommended) and Command Line Tools (xcode-select --install).
• Clone/fork the repo, then open: open "BisonNotes AI/BisonNotes AI.xcodeproj".
• Select the "BisonNotes AI" scheme (iOS) or the watch scheme, choose a Simulator/device, and Run/ Test.
• Branch/PR: create a feature branch in your fork, push changes, and open a PR. Include build/test results and screenshots for UI changes.

Key Features

• Modern v2.0 UI: Recordings, Transcripts, Summaries, Setup, and Settings use refreshed SwiftUI layouts with clearer action placement, sectioned date lists, and adaptive navigation.
• Accessibility-ready task flows (v2.2): VoiceOver and Voice Control labels, values, hints, contextual row summaries, adjustable playback scrubber support, Reduce Motion handling, accessibility UI audits, and App Store accessibility evidence docs cover the common iPhone/iPad, Mac, and Apple Watch workflows.
• Native macOS app (v2.2): Native Apple Silicon Mac target with movable/resizable content windows, dedicated Settings, Mac commands and shortcuts, persistent archive bookmarks, native export/sharing, selectable microphones, optional ScreenCaptureKit meeting audio, and Mac-aware capture recovery.
• Pause and Resume Recording: Pause mid-meeting without stopping the file. Resume seamlessly across iOS, iPadOS, watchOS mute/resume, and Mac (AVAudioEngine/PCM segment path).
• Hardened Credential Storage (v1.11): API keys, AWS credentials, and Bedrock session tokens stored in the iOS Keychain. Legacy values are migrated automatically and kept out of iCloud settings backups. File protection is applied to recordings, transcripts, notes, attachments, and the Core Data SQLite files.
• Endpoint Safety (v1.11): User-configurable OpenAI, OpenAI-compatible, Ollama, and Whisper endpoints are validated — public cleartext (HTTP/WS) destinations are blocked by default; local/private endpoints stay allowed, with a Development Mode toggle for power users.
• Source-Centric Workflow (v1.11): "Generate Transcript" lives on the recording row; "Generate Summary" lives on the transcript. Buttons only appear where they apply and disappear once the artifact exists — regeneration happens from the existing detail view.
• iPhone Action Button Support: Quick-start recording from the Action Button on iPhone 15 Pro/Pro Max, iPhone 16 Pro/Pro Max, and future Pro models. Press the Action Button to launch the app and start recording instantly, even when your phone is locked.
• Watch App & Complications: Single-button Apple Watch recorder with tap-to-record/tap-to-stop, mute as pause/resume on the same file, pulsing capture state, low-battery warning, automatic complete-file sync, and watch-face complications.
• Control Center Recording Widget: Start/stop recordings from Control Center on iOS 18+ via the bundled Controls widget.
• Multiple AI Engines: Support for OpenAI, AWS Bedrock, Google AI Studio, Mistral AI, OpenAI-compatible endpoints, Ollama, On Device AI (MLX Swift), On Device AI Legacy (llama.cpp), and Apple Native (Apple Intelligence).
• Apple Native AI Engine: On-device summarization using Apple's Foundation Models framework (iOS 26+, iPhone 15 Pro+). No data leaves the device.
• On Device AI: Default local summarization path using MLX Swift and Ternary Bonsai models. Supports 4 GB+ devices with model choices scaled by RAM.
• Mistral AI (Free & Paid Tiers): Guided in-app setup wizard for Mistral's free tier -- transcription and summarization with no credit card required. Paid tiers available for higher rate limits. Cloud transcription via Voxtral Mini with speaker diarization support.
• On-Device Processing: Complete privacy with FluidAudio Parakeet transcription and MLX Swift summarization by default on supported devices.
• Comedy Mode: Optional summarization tone (snarky and other styles) applied across engines that support custom prompts.
• Google Calendar Integration: Send tasks or reminders into Google Calendar (app or web fallback) in addition to Apple Reminders/Calendar.
• Summary Attachments: Attach text, PDF, or other documents to a summary and preview them inline (Quick Look fallback for unknown types).
• Recording Title Editing: Edit recording titles directly from the audio player or transcript editor; AI-generated alternative titles are still available from the summary view.
• Audio Export: Share any recording as an audio file via the iOS share sheet
• Audio Archive to iCloud Drive: Offload selected recordings, or recordings older than a chosen age, while keeping transcripts, summaries, and a saved restore pointer in the app. Third-party file providers are disabled for archive targets for now.
• Import From Link: Import direct web URLs for audio/video files and transcript documents. YouTube links are parsed for public caption import; if YouTube blocks the caption request, BisonNotes shows a recovery workflow to open the video, copy the transcript, and import pasted transcript text.
• Video Import: Import video files; audio is automatically extracted to M4A
• Audio Cleanup: Optional pre-transcription DSP processing — high-pass filter, noise gate, dynamic normalization, and peak limiting
• Live Transcription: On-device live speech-to-text via SFSpeechRecognizer during recording; transcript auto-saved on stop
• Share Extension: Import audio and transcript files directly from Voice Memos, Files, and other apps via the iOS share sheet. Token-based authorization prevents the main app from scanning the shared container without an explicit handoff.
• Combine Recordings: Merge two separate recordings into a single continuous audio file
• PDF Export: Professional PDF reports with three-pane header (metadata, local map, regional map), pagination, and dedicated tasks/reminders sections
• Background Processing: Long recordings and complex processing handled automatically in the background with intelligent stale job detection and automatic recovery
• iCloud Backup & Sync: Automatic backup and cross-device reconcile on app activation, CloudKit summary sync with paginated queries and schema-safe fallback, deferred auto-backup, durable recording and summary deletion queues, and a per-recording Keep on This Device tag that excludes a recording, transcript, and summary from BisonNotes iCloud sync and backup. Sensitive settings (API keys, AWS credentials) are excluded from iCloud settings backups by default.
• Search Functionality: Powerful search across recordings, transcripts, and summaries. Search by recording name, transcript text, summary content, tasks, reminders, and titles.
• Date Filters: Filter recordings, transcripts, and summaries by date range. Select start and end dates to quickly find content from specific time periods.

Key Modules

• Recording: EnhancedAudioSessionManager, AudioFileChunkingService, AudioRecorderViewModel (+ +MacEngine, +MacCaptureHealth, +MacFinalization, +MicrophoneReconnection, +Interruptions, +Background, +CallIntelligence, +Warnings), MacRecordingReliability, MacSystemAudioCapture, MacInputDeviceMonitor, RecordingCombiner, TranscriptionStarter
• Transcription: FluidAudioManager (Parakeet), OpenAITranscribeService, MistralTranscribeService, WhisperService, WyomingWhisperClient, AWSTranscribeService, LiveTranscriptionService
• Web Import: WebImportManager, WebImportDownloader, WebImportURLClassifier, YouTubeImportService, YouTubePlayerResponseParser, TranscriptCaptionTextCleaner
• Summarization: OpenAISummarizationService, MistralAISummarizationService, GoogleAIStudioService, AWSBedrockService, OnDeviceLLMService, MLXSwiftEngine, AppleNativeEngine
• Security: KeychainSecretStore, AWSCredentialsManager, AWSClientCredentialResolver, EndpointSecurityPolicy, AppFileProtection
• Export: PDFExportService, SummaryExportFormatter, RecordingArchiveService
• UI: SummariesView, SummaryDetailView, TranscriptionProgressView, AITextView (with MarkdownUI), CombineRecordingsView
• Accessibility: AccessibilitySupport, AccessibilityIdentifiers, UITestSupport, and BisonNotesAIAccessibilityTests
• Persistence: Persistence, CoreDataManager, models under Models/
• Background: BackgroundProcessingManager, TemporaryFileCleanupService
• Watch: WatchConnectivityManager (both targets), BisonNotesComplications (Watch Widget target)
• Controls: RecordingControlWidget (Control Center recording widget)
• Share Extension: ShareViewController (imports audio from other apps via share sheet)
• Action Button: StartRecordingIntent, ActionButtonLaunchManager, AppShortcuts
• Integrations: SystemIntegrationManager (Reminders, Apple Calendar, Google Calendar), IntegrationSelectionView

Audio Archive

Audio archive is different from deleting an audio file. When a recording is archived, BisonNotes exports the audio file to iCloud Drive, stores the archive location in Core Data, and can optionally remove only the local audio file. The recording row, transcript, summary, tasks, reminders, and metadata stay in the app.

Archived recordings show their saved iCloud Drive location and a download button when local audio has been offloaded. Restoring copies the audio back into the app, validates that it is playable audio, clears the archive state, and removes the archived iCloud Drive copy so there is not a second stale file left behind. If the app cannot save a trackable iCloud location, it leaves the local audio in place and does not mark the recording archived.

For now, archive destinations are intentionally limited to iCloud Drive. Dropbox, Google Drive, Proton Drive, and other iOS File Provider extensions can appear in Files, but they have not been reliable enough for batch export, restore, and post-restore deletion.

iCloud Sync Notice

When iCloud Sync is enabled, BisonNotes shows a confirmation notice that BisonNotes AI and uploads to iCloud are not HIPAA-compliant. If enabled, eligible recordings, transcripts, summaries, and selected settings may be uploaded to the user's private iCloud account.

To keep a specific item out of BisonNotes iCloud sync and backup, mark its recording Keep on This Device from the recording row or audio player. The tag applies to the recording's audio, transcript, and summary together. When the tag is turned on, BisonNotes skips future app-managed iCloud summary sync and backup for that item and removes known app-created iCloud records for that recording when iCloud is available.

When iCloud Sync is enabled, BisonNotes automatically reconciles eligible recordings, transcripts, and summaries when the app launches or becomes active. The Include audio files in backup checkbox controls whether audio files are uploaded and restored; transcripts and summaries are included in app-managed iCloud sync unless the recording is marked Keep on This Device. Deleting a recording writes an iCloud deletion marker and removes known app-created iCloud records so other devices on the same iCloud account can apply the deletion before they upload their local state. The app only cleans up records it can prove were deleted or explicitly excluded; active cloud-only records without a deletion marker are restored, while older untrusted cloud-only records are held for review.

Deleting only a summary also creates a durable pending iCloud removal. BisonNotes removes the summary's live record, backup record, and content-index reference immediately when possible, or retries the queued removal when iCloud becomes available.

iOS, iPadOS, and native macOS builds use the shared iCloud container iCloud.Bison-Networking.BisonNotes-AI for app-managed CloudKit sync. Devices must be signed into the same Apple ID and use the same CloudKit environment to see the same records. A local Debug build uses the CloudKit development environment, while TestFlight and App Store builds use production, so a Debug Mac install will not see records created by a production iPhone or iPad build until the build channel/environment matches.

Production iCloud sync requires the CloudKit production schema for iCloud.Bison-Networking.BisonNotes-AI to include the app-managed backup record types CD_BackupRecording, CD_BackupTranscript, CD_BackupSummary, CD_BackupSettings, CD_BackupContentIndex, and CD_BackupDeletion. Before shipping TestFlight or App Store builds that use these records, create/verify them in the development environment and deploy the CloudKit schema changes to production from CloudKit Dashboard. Production clients cannot create new record types themselves.

Current app versions mark synced content as active before it is automatically restored on other devices. Older cloud-only items that are not marked active are held in Settings > iCloud Sync > Review iCloud Items, where they can be restored or deleted from BisonNotes iCloud sync records.

Transcription Engines

The app supports multiple transcription engines for converting audio to text:

Engine	Description	Requirements
On Device (Parakeet)	Default. On-device transcription using NVIDIA Parakeet models. Complete privacy.	iOS 17.0+, model download
OpenAI	Cloud-based transcription using OpenAI's GPT-4o models and Whisper API	API key, internet
Mistral AI	Cloud transcription using Voxtral Mini with speaker diarization ($0.003/min)	API key, internet
Whisper (Local Server)	High-quality transcription using OpenAI's Whisper model on your local server	Whisper server running (REST API or Wyoming protocol)
AWS Transcribe	Cloud-based transcription service with support for long audio files	AWS credentials, internet

OpenAI Transcription Models

OpenAI transcription supports multiple models:

• GPT-4o Transcribe: Most robust transcription with GPT-4o model. Supports streaming for real-time transcription.
• GPT-4o Mini Transcribe: Cheapest and fastest transcription with GPT-4o Mini model. Supports streaming. Recommended for most use cases.
• Whisper-1: Legacy transcription with Whisper V2 model. Does not support streaming.

On Device Transcription

FluidAudio Parakeet (Default)

Parakeet is the sole on-device transcription engine as of v1.8 (WhisperKit was removed). It provides fast, accurate, fully local transcription:

• Privacy: 100% local processing - audio never leaves your device
• Offline: Works completely offline after initial model download
• Requirements: iOS 17.0 or later
• Models: Parakeet v2 for English long-form recall and Parakeet v3 for multilingual transcription across 25 European languages
• Reliability: v2.1 recognizes valid cached model files, restores the selected model version when possible, resets stale download state when files are gone, and absorbs very short final tail chunks during long on-device transcriptions
• Migration: Existing users who had WhisperKit selected are automatically switched to Parakeet on first launch of v1.8

Mistral AI Transcription

Mistral AI transcription uses the Voxtral Mini model for cloud-based speech-to-text:

• Model: Voxtral Mini Transcribe (voxtral-mini-latest)
• Cost: $0.003 per minute of audio
• Speaker Diarization: Optional — identifies and labels different speakers in the audio
• Language: Automatic detection or explicit language code (e.g., en, fr, es)
• Supported Formats: MP3, MP4, M4A, WAV, FLAC, OGG, WebM
• Chunking: Automatic chunking for files over 24MB or ~22 minutes (combined size/duration strategy)
• Setup: Uses the same API key as Mistral AI summarization. Configure in Setup → AI Settings → Mistral AI, then select Mistral AI as your transcription engine in Transcription Settings.

AI Engines

The app supports multiple AI engines for summarization and content analysis:

Engine	Description	Requirements
Apple Native	Apple Intelligence (Foundation Models) — fully on-device	iOS 26+, iPhone 15 Pro+
OpenAI	GPT-4.1 Mini, GPT-5 Mini, GPT-5.4 Mini	API key, internet
OpenAI Compatible	Any OpenAI-compatible API (Nebius, Groq, LiteLLM, llama.cpp, etc.)	API key, internet
Mistral AI	Mistral Large (25.12), Medium (25.08), Magistral Medium (25.09)	API key, internet
Google AI Studio	Gemini 3 Flash Preview (default), Gemini 3.1 Flash Lite Preview	API key, internet
AWS Bedrock	Claude 4.5 Haiku, Claude Sonnet 4.5, Llama 4 Maverick 17B Instruct	AWS credentials
Ollama	Local LLM server (recommended: qwen3:30b, gpt-oss:20b, mistral-small3.2)	Ollama server running
On Device AI	Default on-device summarization with MLX Swift and Ternary Bonsai models	4 GB+ RAM, model download
On Device AI (Legacy)	Fully offline llama.cpp summaries with GGUF models	6 GB+ RAM, model download

OpenAI Models

OpenAI summarization supports multiple models:

• GPT-4.1 Mini: Balanced performance and cost, suitable for most summarization tasks (Standard tier) - Default
• GPT-5 Mini: Next-generation reasoning model with enhanced efficiency (Premium tier)
• GPT-5.4 Mini: Latest GPT-5 mini with improved reasoning and efficiency (Premium tier)

AWS Bedrock Models

AWS Bedrock provides access to multiple foundation models:

• Claude 4.5 Haiku: Fast and efficient model optimized for quick responses (Standard tier) - Default
• Claude Sonnet 4.5: Latest Claude Sonnet with advanced reasoning, coding, and analysis capabilities (Premium tier)
• Llama 4 Maverick 17B Instruct: Meta's latest Llama 4 model with enhanced reasoning and performance (Economy tier)

Mistral AI Models

Mistral AI offers a free Experiment tier (no credit card required) with access to all models, plus paid Build and Scale tiers for higher rate limits. The app includes a guided in-app setup wizard that walks new users through account creation and API key provisioning in about 2 minutes. See Mistral AI Free Setup Guide for details.

Summarization models:

• Mistral Large (25.12): Most capable Mistral model with 128K context window (Premium tier)
• Mistral Medium (25.08): Balanced performance and cost with 128K context (Standard tier)
• Magistral Medium (25.09): Economy option with 40K context window (Economy tier)

Google AI Studio Models

Google AI Studio provides access to Gemini models:

• Gemini 3 Flash Preview: Fast and efficient — Default (gemini-3-flash-preview)
• Gemini 3.1 Flash Lite Preview: Lightweight variant for quick processing (gemini-3.1-flash-lite-preview)

On-Device AI

The on-device AI feature enables completely private, offline AI processing. v2.1 uses MLX Swift as the default local summarization engine and keeps the original llama.cpp engine as a legacy option for higher-memory devices.

MLX Swift (Default)

• 4GB+ RAM: Ternary Bonsai 1.7B (~470 MB) - compact model for devices with limited memory
• 6GB+ RAM: Ternary Bonsai 4B (~1.1 GB) - default model for most supported devices
• 8GB+ RAM: Ternary Bonsai 8B (~2.3 GB) - slower but higher-quality summaries
• Native macOS, 16GB+ RAM: Ternary Bonsai 27B (~8.5 GB) - laptop-class reasoning; unavailable on iOS
• Context Window: 16K tokens
• Migration: Existing users on the removed LFM model or legacy llama on sub-6GB devices are moved to MLX 1.7B when possible. Devices below 4GB fall back to Mistral AI.

On-Device AI Legacy (llama.cpp)

• Recommended Models (by device RAM):

  • 8GB+ RAM: Gemma 3n E4B (4.5 GB) - Best overall quality
  • 6GB+ RAM: Gemma 3n E2B (3.0 GB) - Good quality, smaller size
  • 6GB+ RAM: Granite 4.0 Micro (2.1 GB) - Very fast processing

• Experimental Models (enable in settings):

  • 8GB+ RAM: Granite 4.0 H Tiny (4.3 GB) - Reliable and accurate
  • 6GB+ RAM: Ministral 3B (2.1 GB) - Best for tasks and reminders
  • 6GB+ RAM: Qwen3.5 2B (1.3 GB) - Latest Qwen3.5 model, thinking mode (summary only)
  • 8GB+ RAM: Qwen3.5 4B (2.7 GB) - Excellent detail extraction, thinking mode

• Quantization: Q4_K_M only (optimal balance of quality and memory usage)

• Storage: Models stored in Application Support (1.3 GB - 4.5 GB each)

• Context Window: 16K tokens (automatically adjusted based on device RAM)

• Requirements:

  • Transcription: iOS 17.0+, 4GB+ RAM (most modern iPhones and iPads). Uses Parakeet on-device transcription by default when supported (requires model download)
  • AI Summary: MLX Swift requires 4GB+ RAM. Legacy llama.cpp models require 6GB+ RAM. Apple Native requires iOS 26+ and an Apple Intelligence-capable device.
  • Device capability check prevents downloads on unsupported devices
  • Models are filtered based on available RAM

• Downloads: WiFi by default with optional cellular download support

Configuration

• Secrets are entered in‑app via setup views (OpenAI, Mistral AI, Google, AWS, Ollama, Whisper). All keys/tokens are persisted to the iOS Keychain through KeychainSecretStore; legacy UserDefaults values are migrated automatically on first launch of v1.11. Do not commit API keys.
• AWS process-environment credentials (AWS_ACCESS_KEY_ID etc.) are cleared at launch; Bedrock, Transcribe, and background jobs use explicit credential resolvers from AWSCredentialsManager.
• User-configurable AI endpoints (OpenAI/OpenAI-Compatible/Ollama/Whisper) are validated via EndpointSecurityPolicy — public cleartext destinations are blocked unless the per-service Development Mode override is enabled.
• Enable required capabilities in Xcode (Microphone, Background Modes, iCloud if used). Keep Info.plist and .entitlements aligned with features. APS_ENVIRONMENT is set per-configuration so Debug uses development and Release uses production.
• Before distributing iCloud sync changes through TestFlight or the App Store, deploy CloudKit development schema changes for iCloud.Bison-Networking.BisonNotes-AI to production. Production builds cannot create new CloudKit record types at runtime.
• For On Device transcription, Parakeet is the only on-device engine (WhisperKit was removed in v1.8). Download the model in Setup → Transcription Settings → On Device.
• For on-device AI, device capability checks ensure your device meets requirements (4 GB+ RAM for MLX Swift, 6 GB+ RAM for legacy llama.cpp models, iOS 26+ and an Apple Intelligence-capable device for Apple Native) before allowing downloads.

iPhone Action Button Setup

If you have an iPhone 15 Pro, iPhone 15 Pro Max, iPhone 16 Pro, iPhone 16 Pro Max, or future iPhone Pro models with an Action Button, you can configure it to start recording instantly:

1. Open Settings on your iPhone
2. Tap Action Button
3. Select Shortcut
4. Choose "Start Recording" from BisonNotes AI
5. Press the Action Button to test - it will launch BisonNotes AI and start recording automatically!

What happens when you press the Action Button:

• The app opens automatically (even if it was closed)
• Switches to the Recordings tab
• Recording starts immediately without needing to tap the microphone button
• Recording continues in the background if you switch apps or lock your phone

The Action Button works even when your phone is locked, making it perfect for quick voice notes!

Search and Filtering

The app includes powerful search and filtering capabilities to help you find your recordings, transcripts, and summaries quickly.

Search Functionality

Search is available in three main views:

• Summaries View: Search across summary content, tasks, reminders, titles, and recording names
• Transcripts View: Search through transcript text and recording names
• Recordings View: Search by recording name

How to use:

• Tap the search bar at the top of any view
• Type your search terms
• Results filter in real-time as you type
• Search is case-insensitive and matches partial text

Date Filters

Date range filtering helps you find content from specific time periods:

• Available in: Summaries, Transcripts, and Recordings views
• How to use:
  1. Tap the filter icon (three horizontal lines with circle) in the navigation bar
  2. Select a start date and end date
  3. Tap "Apply" to filter results
  4. The active filter is shown with a banner at the top of the list
  5. Tap the X on the banner to clear the filter

Filter Behavior:

• Filters can be combined with search for precise results
• Date range includes the full day (00:00:00 to 23:59:59) for both start and end dates
• Filters persist until manually cleared

Share Extension

Import audio and transcript files from other apps directly into BisonNotes AI using the iPhone, iPad, or Mac Share menu:

• Supported audio formats: M4A, MP3, WAV, CAF, AIFF, AIF
• Supported document formats: TXT, MD, VTT, SRT, PDF, DOC, DOCX
• How it works:
  1. Open Voice Memos, Files, Finder, or another app with an audio or transcript file
  2. Tap or click the share button and select "BisonNotes AI"
  3. The file is saved to the protected shared container
  4. BisonNotes AI opens or is notified and imports the file
• Background import: If the main app is already running, a Darwin notification wakes it to scan for new files immediately
• Busy import handling: If another import is active, the new file remains staged and is retried on a later app activation instead of being discarded
• File naming: Imported files are prefixed with a UUID to prevent name collisions

Import From Link

Import audio, video, and transcript content from web addresses without downloading the file manually first:

• Where to start: Tap Import From Link on the Recordings screen, or use File > Import From Link... on Mac.
• Direct audio/video URLs: Supported media links include M4A, MP3, WAV, CAF, AIFF, AIF, MP4, MOV, M4V, AVI, and MKV. Video imports extract the audio to M4A for transcription.
• Direct transcript URLs: Supported transcript/document links include TXT, MD, VTT, SRT, PDF, DOC, and DOCX. Imported transcripts can be summarized without an audio file.
• YouTube links: YouTube share links are recognized and the app attempts to import public captions as a transcript. YouTube audio/video is not downloaded directly.
• YouTube recovery flow: If YouTube blocks the caption request, the sheet shows directions, an Open YouTube Video button, and a pasted-transcript import box. Copy the transcript from YouTube, paste it into BisonNotes, and import it for summary generation.
• Endpoint safety: Public HTTP links are blocked. Use HTTPS, localhost, or private-network addresses.

Combine Recordings

Merge two separate recordings into a single continuous audio file:

1. Open the Recordings tab
2. Enter selection mode and tap the checkbox next to two recordings
3. Tap "Combine" to open the combination interface
4. Choose the playback order (which recording comes first)
5. Preview the combined duration, then tap "Combine Recordings"
6. The new combined recording appears in your list; optionally delete the originals

Requirements: Both recordings must have no existing transcripts or summaries. Delete any transcripts/summaries first, then combine. After combining, generate new transcripts and summaries for the merged file.

Acknowledgments

BisonNotes AI is built on the shoulders of several outstanding open-source projects. We gratefully acknowledge the following:

Direct Dependencies

Project	Description	License	Link
Textual	Markdown rendering library used to display AI-generated summaries, transcripts, and formatted content.	MIT	gonzalezreal/Textual
FluidAudio	On-device speech framework powering Parakeet transcription.	Apache 2.0	FluidInference/FluidAudio
MLX Swift / MLX Swift LM	Apple Silicon ML framework and language-model utilities used for on-device summarization with Ternary Bonsai models.	MIT	ml-explore/mlx-swift / ml-explore/mlx-swift-lm
llama.cpp	C/C++ inference engine for on-device LLM processing. Embedded as a pre-compiled xcframework for Metal-accelerated local AI summarization.	MIT	ggerganov/llama.cpp
AWS SDK for Swift	Cloud services SDK powering AWS Bedrock (Claude, Llama), Transcribe, and S3 integrations.	Apache 2.0	awslabs/aws-sdk-swift
Swift Transformers	Hugging Face tokenizers and transformer utilities for local ML model pipelines.	Apache 2.0	huggingface/swift-transformers

Transitive Dependencies

The AWS SDK and other direct dependencies bring in a number of excellent open-source libraries from the Apple Swift ecosystem and broader community:

• Apple Swift Server libraries: Swift NIO, Swift NIO Extras, Swift NIO HTTP/2, Swift NIO SSL, Swift NIO Transport Services, Swift Crypto, Swift Protobuf, Swift Collections, Swift Algorithms, Swift Log, Swift Metrics, Swift Atomics, Swift System, Swift Async Algorithms, Swift Argument Parser, Swift Numerics, Swift Certificates, Swift ASN1, Swift HTTP Types, Swift HTTP Structured Headers, Swift Distributed Tracing, Swift Service Context, and Swift Configuration
• Swift Server community: Async HTTP Client, Swift Service Lifecycle
• Networking and data utilities: EventSource, yyjson
• gRPC: gRPC Swift
• Observability: OpenTelemetry Swift
• AWS infrastructure: AWS CRT Swift, Smithy Swift
• Hugging Face: Swift Jinja, Swift HuggingFace
• UI support: SwiftUI Math
• Point-Free: Swift Concurrency Extras

All dependencies are MIT or Apache 2.0 licensed. See each project's repository for full license terms.

Contributing

Follow the Local Dev Setup above to run and validate changes before opening a PR.

License

See LICENSE.