How to Use NCKit

Step-by-step guide for developers new to NCKit. No sample-app UI required — copy the patterns below into your project.

Before you start

1. Install NCKit — iOS: confirm Embed & Sign
2. iOS: physical iPhone/iPad or Apple Silicon simulator (requirements)
3. Imports compile in your target

---

Choose your use case

Goal	NCKit API	Difficulty
Denoise an existing audio/video file (WAV, M4A, MP4, …)	NCKitFileProcessor	Easiest — start here
Denoise live microphone in real time	NCKitStreamProcessor	Recommended — sample: Audio tab

Most apps only need file denoise (processFile). Live mic uses NCKitStreamProcessor with AVAudioEngine — see Sample App.

---

How NCKit fits together (every integration)

All paths use the same two setup calls, then one processing call:

1. let modelURL = try NCKitModelLocator.modelTarGzURL()
2. let processor = try NCKitProcessor(modelURL: modelURL)
3. Process audio  →  file: NCKitFileProcessor.processFile(...)
                    →  live:  NCKitStreamProcessor.process(buffer:)  (recommended)

Create the processor once and reuse it. Creating a new NCKitProcessor per file costs ~50–200 ms each time.

---

Path A — Denoise a file (recommended first integration)

Step 1 — Import

import NCKit

Step 2 — Copy-paste service (file denoise)

Same pattern as the NCKit Sample AudioEngine / VideoProcessor — one shared NCKitProcessor per session.

Add this to your project. Call denoiseFile from a background thread when the user picks a file.

import NCKit
import Foundation

enum DenoiseService {
    /// Reuse one processor for the app session (create on first use).
    private static var processor: NCKitProcessor?

    private static func processorInstance() throws -> NCKitProcessor {
        if let processor { return processor }
        let modelURL = try NCKitModelLocator.modelTarGzURL()
        let p = try NCKitProcessor(modelURL: modelURL, attenLimDb: 100, postFilterBeta: 0)
        processor = p
        return p
    }

    /// Denoise `inputURL` and return a new 48 kHz mono WAV URL.
    static func denoiseFile(inputURL: URL) async throws -> URL {
        let outputURL = FileManager.default.temporaryDirectory
            .appendingPathComponent(UUID().uuidString + "_clean.wav")

        return try await Task.detached(priority: .userInitiated) {
            let proc = try processorInstance()
            try NCKitFileProcessor.processFile(
                inputURL: inputURL,
                outputURL: outputURL,
                processor: proc
            )
            return outputURL
        }.value
    }
}

Step 3 — Call it

// Example: user picked a file (after security-scoped access if needed)
Task {
    do {
        let cleanURL = try await DenoiseService.denoiseFile(inputURL: pickedFileURL)
        // Play, upload, or save cleanURL (16-bit PCM WAV)
    } catch let error as NCKitError {
        print("NCKit error: \(error)")
    } catch {
        print("Other error: \(error)")
    }
}

User-selected files (important)

let accessed = inputURL.startAccessingSecurityScopedResource()
defer { if accessed { inputURL.stopAccessingSecurityScopedResource() } }
let cleanURL = try await DenoiseService.denoiseFile(inputURL: inputURL)

Without proper file access, you may get cannotOpenInput / CannotOpenInput even when the file looks valid.

What you get back

• Input: Any format AVAudioFile can read (WAV, M4A, MP3, MP4, …)
• Output: 16-bit PCM WAV, 48 kHz, mono
• Memory: streaming — safe for long files

API details: NCKitFileProcessor

---

Path B — Real-time microphone (advanced)

Use this when you already have (or can build) a live audio capture pipeline.

Extra requirements

- NSMicrophoneUsageDescription in Info.plist
- Mic permission before starting AVAudioEngine
- NCKitStreamProcessor on the audio tap thread (not thread-safe)

Minimal flow

import NCKit
import AVFoundation

// 1. Setup processor + stream adapter
let modelURL = try NCKitModelLocator.modelTarGzURL()
let processor = try NCKitProcessor(modelURL: modelURL)
let stream = NCKitStreamProcessor(processor: processor)

// 2. Configure audio session
let session = AVAudioSession.sharedInstance()
try session.setCategory(.playAndRecord, mode: .measurement, options: [.defaultToSpeaker])
try session.setPreferredSampleRate(48_000)
try session.setActive(true)

// 3. Install microphone tap
inputNode.installTap(onBus: 0, bufferSize: 4096, format: tapFormat) { buffer, _ in
    try stream.prepare(inputFormat: buffer.format)
    let frames = try stream.process(buffer: buffer)
    for frame in frames {
        // 480 Float samples @ 48 kHz mono — denoised
    }
}

Dry + denoised (A/B)

try stream.prepare(inputFormat: buffer.format)
let dry = try stream.convertToTargetFormat(buffer)
let denoised = try stream.processConverted(dry)

End of session

let tail = try stream.flush()
stream.reset()  // requires NCKit 1.1.1+

Reference: NCKit_Demo/AudioEngine.swift. API: NCKitStreamProcessor.

Dry + denoised (A/B)

NCKit does not set up AudioRecord / AudioTrack for you — see Nckit_Android_Sample_App AudioEngine.kt. API details: NCKitStreamProcessor.

Direct file denoise without custom audio code

API details: NCKitProcessor

---

Handle errors

} catch NCKitError.missingModel {
    // Framework not embedded correctly — check Embed & Sign
} catch NCKitError.libraryInit {
    // Intel simulator or corrupt model — use a real device
} catch NCKitError.cannotOpenInput {
    // Bad URL or missing security-scoped access
} catch NCKitError.unsupportedFormat {
    // Unsupported audio format
} catch NCKitError.resampleFailed {
    // AVAudioConverter failure
} catch {
    print("Unexpected: \(error)")
}

Full list: NCKitError · Fixes: Common Errors

---

Common mistakes (new integrators)

Mistake	Fix
Framework not Embed & Sign	Target → General → Frameworks
NCKitStreamProcessor from multiple threads	Use audio tap thread only
New NCKitProcessor per file	Reuse one instance (see DenoiseService above)
Intel Mac simulator	Upgrade to 1.2.1+ or use Rosetta / device
User-picked file won't open	Enable security-scoped resource access
reset() missing	Upgrade to 1.2.1 (or 1.1.1+) and reset package caches
Denoise blocks UI	Use Task.detached for processFile
Expecting NCKit to build UI	NCKit is audio processing only — UI is your app

---

---

Optional: loudness normalization

See NCKitAudioNormalizer.

---

API reference (lookup)

Type	Page
NCKitModelLocator	Model path
NCKitProcessor	Processor
NCKitStreamProcessor	Live audio
NCKitFileProcessor	File denoise
NCKitAudioNormalizer	Normalization
NCKitError	Errors