Skip to content

Logging, Signals and Error Handling ​

RecordKit provides structured logging, signals and user-friendly errors to help you debug issues and keep your users informed.

Logging ​

By default, RecordKit logs to the system console. You can forward logs to your own logging infrastructure (SwiftLog, electron-log, etc.) and control verbosity with log levels.

Set the log level using setLogLevel(). Available levels from most to least verbose: trace, debug (default), info, warning, error, critical.

swift
RKLogger.shared.setLogLevel(.info)
ts
// During initialization
await recordkit.initialize({
    rpcBinaryPath: path.join(process.resourcesPath, 'recordkit-rpc'),
    logLevel: 'info'
})

// Or after initialization
await recordkit.setLogLevel('info')

Forwarding Logs ​

Connect RecordKit's logs to your existing logging setup.

swift
import Logging
import RecordKit

private let logger = Logger(label: "RecordKit")

// Forward RecordKit logs to SwiftLog
func setupRecordKitLogging() {
    RKLogger.shared.setLogLevel(.debug)
    RKLogger.shared.setLogHandler(mode: .realtime) { message in
        let level: Logger.Level = switch message.level {
        case .trace:    .trace
        case .debug:    .debug
        case .info:     .info
        case .warning:  .warning
        case .error:    .error
        case .critical: .critical
        @unknown default: .info
        }
        logger.log(level: level, "[\(message.category)] \(message.message)")
    }
}
ts
recordkit.on('log', (event) => {
    // Forward to your logging system
    myLogger.log(event.formattedMessage)
})

Handler Modes

In Swift, .realtime delivers logs inline, but your handler must be fast to avoid blocking RecordKit. .nonblocking (default) delivers logs on a background thread, so your handler won't block RecordKit even if it's slow. In Electron, logs are always delivered non-blocking.

For per-category log levels and more, see the API reference: Swift | Electron

Signals ​

Signals let you know about events you might want to act on while the recording still continues. For example a disconnected microphone or disk space running low. Based on the use case of your app you decide how you react to them.

SignalRaised when
disconnectedA recorded microphone became unavailable
mutedA microphone is muted
noAudioOnly silence was received for the last 10 seconds
lowDiskSpaceFree disk space dropped below 150 MB

Your handler receives all signals that are active at that moment, every time that list changes. A signal stays in the list for as long as its condition holds, an empty list means everything is fine again.

swift
let recorder = RKRecorder(
    [.microphone(microphoneID: microphone.id)],
    onAbort: { reason in
        // The recording ended, see Error Handling below
    },
    onSignalsChanged: { signals in
        // All active signals, an empty array means everything is fine again
        let warnings = signals.map { signal in
            switch signal.kind {
            case .disconnected: "Your microphone is disconnected."
            case .muted:        "Your microphone is muted."
            case .noAudio:      "We don't hear anything from your microphone."
            case .lowDiskSpace: "Your disk is almost full."
            @unknown default:   "Something is off with your recording."
            }
        }
        Task { @MainActor in showWarnings(warnings) }
    }
)
ts
const recorder = await recordkit.createRecorder({
    items: [
        { type: 'microphone', microphone: microphone }
    ]
})

recorder.on('signals', (signals) => {
    // All active signals, an empty array means everything is fine again
    showWarnings(signals.map((signal) => {
        switch (signal.kind) {
            case 'disconnected': return 'Your microphone is disconnected.'
            case 'muted':        return 'Your microphone is muted.'
            case 'noAudio':      return "We don't hear anything from your microphone."
            case 'lowDiskSpace': return 'Your disk is almost full.'
        }
    }))
})

No audio from system audio

System audio is silent whenever nothing is playing, so whether noAudio for system audio is worth a warning depends on what your app records.

See the API reference: Swift | Electron

Error Handling ​

RecordKit errors are designed to be shown directly to users. Every error includes:

  • A user-friendly message that explains what went wrong, safe to display in your UI
  • A technical description with details useful for logging and troubleshooting
swift
do {
    try await recorder.start()
} catch {
    // User-friendly message, e.g. "Can't record 'Cinema Display' because it is not connected anymore."
    showAlert(message: error.localizedDescription)

    // Technical details, e.g. "displayUnavailable - RKDisplay 12345 has availability: notConnected"
    logger.error("Recording failed: \((error as NSError).debugDescription)")
}
ts
try {
    await recorder.start()
} catch (error) {
    // User-friendly message, e.g. "Can't record 'Cinema Display' because it is not connected anymore."
    dialog.showErrorBox('Recording Failed', error.message)

    // Technical details, e.g. "displayUnavailable - RKDisplay 12345 has availability: notConnected"
    console.error('Recording failed:', error.debugDescription)
}

For all error codes, see the API reference.

Questions? Feel free to contact us at [email protected]