lgvv98

SwiftUI의 새로운 기능 (Explore related documentation, sample code, and more) -wwdc25

lgvv — Sat, 2 May 2026 16:21:35 +0900

SwiftUI의 새로운 기능 (Explore related documentation, sample code, and more)

SwiftUI의 저성능 관련 개선사항부터 UI상의 버튼에 이르기까지 시스템 전반에 걸쳐 개선

Make the new design shine
- 새로운 모든 시스템 기능 리뷰
Framework foundations
- 성능과 애니메이션, 레이아웃 관련 개선사항 공유
SwiftUI across the system
- Apple 플랫폼 전반에 걸쳐 SwiftUI를 사용할 수 있는 새로운 환경 소개
Expand SwiftUI views
- 웹 콘텐츠, 리치 텍스트 지원 등 SwiftUI 뷰의 새 기능에 대해 알아볼 것.

Make the new design shine

네비게이션, 버튼, 탭바, macOS, PadOS 등 디자인이 변경되었음

아이템 간 간격은 toolbar의 Spacer API를 사용해 조정.

Liquid Glass는 색조를 지원하기도 하는데 스타일과 색상을 적용하면 됨.

검색 위해 코드를 변경할 필요가 없이 패드, 폰, 맥 등에 한번에 적용됨.

외관을 새롭게 하려면 role에 search를 두어 역할을 갖도록 설정

Liquid Glass는 커스텀하게도 사용할 수 있음.

macOS에서 메뉴 막대 구축시 `.commands` API를 사용했었고, 아이패드에서도 같은 결과를 낼 수 있음.

사용자가 앱 사이즈를 자유롭게 조절할 수 있음.

SplitView를 사용하는 앱은 시스템이 가능한 공간에 따라 자동으로 열을 숨기거나 보임.

앱 크기 조정 기능을 구현하려면 UIRequiresFullScreen과 같이 화면을 전체 크기로 고정하는 API를 외부로 마이그레이션.

UIRequiresFullScreen 이건 PadOS 26에서 더 이상 지원되지 않음.

아이패드 사이즈 조정에 대한 부분을 확인하려면 Elevate the design of your iPad app(WWDC25) 확인

macOS에서도 windowResizeAnchor를 이용해서 사이즈를 동적으로 대응할 수 있음.

Framework foundations

강력한 성능 부터 사용 편의성 개선 및 새로운 콘텐츠 레이아웃에 이르기까지 SwiftUI로 앱을 개발하기 좋은 시점.

프레임워크 성능 개선 또한 여러 앱을 포함해 Apple 플랫폼 전반의 모든 앱에 이점을 가져다 줌.

SwiftUI에서 Lists, Scrolling, Profiling and Debugging이 개선되었음.

macOS에서는 10만개 항목 리스트 로딩이 6배, 업데이트는 최대 16배 더 빠르게 업데이트 됨.

리스트가 클수록 성능이 더 크게 향상되며, 플랫폼 전반에 적용.

SwiftUI가 다음 스크롤링하면 다음 프레임을 렌더링할 수 있도록 함.

하지만 Deadline까지 모든 작업이 완료되지 않으면 프레임이 떨어지게 됨.

iOS 및 macOS는 UI 업데이트를 통해 SwiftUI 스케줄링 경험이 개선

반응성을 향상시키고 SwiftUI가 다음 프레임에 대비해 더 많은 작업을 처리하도록 해줌.

이로 인해서 많은 스크롤을 하는 동안 앱이 중단될 가능성을 줄여줌.

LazyVStack을 ScrollView 안에 넣을 때 SwiftUI가 뷰가 나타나기 직전까지 로딩을 지연시킴

중첩된 ScrollView도 이와 같이 동일하게 동작함.

예를 들어서, 사진 캐러셀과 같은 뷰를 만드는데 좋음.

앱에 어떤 성능 문제가 남아 있는지 이해하려면 Xcode에서 SwiftUI 성능 도구를 사용하면 됨.

긴 body를 업데이트 또는 View 업데이트와 같은 다양한 성능 문제 영역에서 문제를 확인하고 조치할 여러가지 방법을 사용할 수 있음.

Optimize SwiftUI performance with instruments에서 상세한 정보를 확인할 수 있음.

또한 동시성에 부분을 확인하려면 위의 영상 참고할 것

애니메이션에는 AnimatableData이라는 프로토콜을 사용함.

드로잉 방향을 제외한 모든 모앙야 데한 속성을 애니메이션화 함.

전체 애니메이션 데이터 선언을 추가할 때 드로잉 방향을 제외하는 것만 해도 코드가 정말 많은데, 새로운 애니메이션 매크로(@Animatable)를 사용하면, 사용자 지정 애니메이션 데이터 속성을 삭제하고, SwiftUI로 하여금 자동으로 합성하도록 만들 수 있음.

드로잉 방향처럼 애니메이션을 원하지 않는 속성의 경우 @AnimatableIgnored을 사용해서 제외.

레이아웃은 이제 3차원으로 작업하는데 SwiftUI에는 이미 익숙한 수정자에 새로운 깊이 기반 변형이 도입되어, 직접적인 volumetic layout 없이도 더 많은 작업이 가능함.

VisionOS 앱에서 3D가 적합한데, 새로운 Alignment3D를 활용하면 시간에 따른 정렬을 조정할 수 있음.

이건 VisionOS 26의 공간 레이아웃 개선사항으로 Meet SwiftUI spatial layout (WWDC25)를 확인.

SwiftUI across the system

앱은 시스템 전반에 걸쳐 SwiftUI의 이점을 활용할 수 있음.

Scene에 대한 개선사항과 Widget 및 Control과 관련한 새로운 API 덕분에 앱이 플랫폼과 정말 잘 어우러짐.

SwiftUI는 다른 프레임워크와는 훨씬 더 잘 작동함.

Scene은 앱의 뷰에 대한 루트 컨테이너로 인터페이스의 분리된 부분을 나타냄.

앱의 `body` 영역에 선언하여 Scene에 접근할 수 있음.

올해부터는 Scene 브릿징을 통해 UIKit과 AppKit 라이프사이클 앱에서 SwiftUI의 Scene 요청이 가능함.

Scene bridging을 통해서 UIKit과 AppKit에서 라이프사이클 상호운용 가능함.

이를 통해서 SwiftUI에 있는 Scene 타입을 열거나 UIKit 또는 AppKit에서 바로 SwiftUI 기능을 사용할 수 있음.

MenuBarExtra나 ImmersiveSpace 같은 Scene 타입 등을 사용할 수 있음.

WindowStyle 등 다양한 Modifier와도 잘 작동함.

인지 장애가 있는 사용자를 위한 특수 모드인 AssistiveAcess가 존재.

올해 SwiftUI에는 AppKit 작업에 몇가지 큰 개선사항이 있음.

Scene bridging 외에도 SwiftUI 뷰가 있는 시트도 표시할 수 있음.

AppKit 제스처도 SwiftUI로 연결할 수 있음.

interface Builder에서 NSHostingView를 사용할 수 있음.

watchOS 26과 macOS Tahoe는 커스텀 제어 기능을 제공함.

올해부터는 위젯을 VisionOS와 CarPlay에서 사용할 수 있음.

VisionOS는 새로운 레벨 환경 변수를 사용해서 공간을 사용자가 지정할 수 있음.

푸시 기반 업데이트 API 등 올해 여러가지가 새롭게 나옴.

SwiftUI View 기능이 확장되었는데, 리치 텍스트 편집부터 3D 차트에 이르기까지 기존 SwiftUI의 기능과 외관이 새롭게 단장됨.

앱에서 웹 콘텐츠를 곧바로 임베드 할 때 WebKit에서 WebView와 같은 SwiftUI API 전체를 활용할 수 있음.

WebView는 앱에서 웹 콘텐츠를 표시하는 새로운 SwiftUI 뷰로 Safari와 동일하게 WebKit으로 구동.

페이지를 커스텀하고 이와 상호작용하려면 WebView로 새 observable 모델 유형인 WebPage를 표시할 수 있음.

WebPage는 웹과 풍부한 상호작용을 가능하도록 하는데, 프로그래밍을 통해 페이지에서 탐색하고 페이지 속성에 접근함.

WebKit이 SwiftUI를 지원하는 새로운 방법으로 사용자 에이전트 커스텀이나 JavaScript 호출, 커스텀 URL 스킴 등이 생겼고 더 다양해짐.

Chart3D를 통해서 3차원 플롯을 보여줄수도 있음.

올해는 mac에 드래그를 도입해서 여러 항목 주변으로 드래그를 할 수 있음.
새로운 dragContainer도 macOS에서 사용할 수 있음.

이렇게 하면 뷰가 드래그 항목을 담는 컨테이너와 동일해지며, 커스텀 선택 동작과도 함께 작동함.

드래그 앤 드롭이 실행될 때 항목은 지연 드래그하도록 SwiftUI가 자동으로 요청함.

신규 `dragCofiguration` api로 드래그 작업을 사용자화 할 수도 있음.

`onDragSessionUpdated`는 이벤트를 관찰 가능하도록 함.

`dragPreviewsFormation`은 드래그 할 때 미리보기가 어떻게 뜨는지 확인하기 위해서 사용

TextView에 이제 AttributedString이 지원됨.

TextEditor에서 AttributedString에 바인딩을 통해 내장형 텍스트 포맷팅 제어 기능을 사용할 수 있음.

(참고)

https://www.youtube.com/watch?v=cETgTtu6atM

defer로 인해 lock의 범위가 넓어져 발생한 문제 분석

lgvv — Thu, 26 Mar 2026 17:02:00 +0900

defer로 인해 lock의 범위가 넓어져 발생한 문제 분석

동시성 코드에서 lock은 가장 직관적인 장치 중 하나로 여러 스레드가 같은 상태를 동시에 읽고 쓰면 race condition이 발생할 수 있기 때문에 공유 자원을 보호하기 위해 lock을 사용.

문제는 아래의 코드 패턴은 락의 범위를 함수 끝까지 늘려서 이 경우 후속 로직에서 lock을 다시 잡아야 하는 코드가 존재면 문제가 발생할 수 있음.

func foo() {
    lock.lock()
    defer { lock.unlock() }
    
    // do something
}

문제가 발생하는 코드 예시

락을 잡은 채 기다리는 구조가 생기면 장기 대기나 데드락으로 이어질 수 있음.
특히 코드와 로직이 복잡할수록 원인이 코드 한가운데에 숨어 있어 발견하기 어려움.

func someFunction() {
    lock.lock()
    defer { lock.unlock() }

    // 상태 변경
    isCompleted = false
    
    // callback이 signal 해줘야 함
    finished.wait()
}

func callback() {
    lock.lock()
    defer { lock.unlock() }
    
    // 상태 변경
    isCompleted = true

    finished.signal()
}

lock은 상태만 보호하기

락의 역할은 공유 상태를 안전하게 읽고 쓰는 것이 목적이라서 가급적 짧게 유지해야 함.

defer로 lock 범위가 넓어진 상태에서 오래 기다릴 수 있는 작업까지 임계구역에 들어갈 경우 lock이 상태 보호의 도구를 넘어 흐름을 차단하는 장치로 동작하게 됨.

따라서 lock은 상태를 보호하기 위해서 짧게 사용하고, 대기하는 작업은 반드시 lock 밖에서 사용하기.

기기별 RAM 용량에 따른 이미지 동적 캐시 사이즈 설계

lgvv — Wed, 25 Mar 2026 23:02:57 +0900

기기별 RAM 용량에 따른 이미지 동적 캐시 사이즈 설계

글로벌 서비스를 운영하다 보면, 여전히 RAM 2GB~3GB 수준의 구형 기기 사용자를 무시할 수 없음.
iPhone 8, iPhone SE 1세대, 일부 보급형 기기처럼 메모리 여유가 크지 않은 환경에서는, 캐시 전략 하나만으로도 앱 안정성이 크게 달라질 수 있음.

이미지 캐시는 사용자 경험을 빠르게 만들기 위한 중요한 장치지만, 동시에 메모리를 많이 사용하는 기능이기도 함.
그래서 캐시 크기를 고정값으로 두면 다음과 같은 문제가 생김

저사양 기기에서는 메모리 압박으로 크래시 위험이 커짐
고사양 기기에서는 더 많은 자원을 활용하지 못해 비효율이 발생함

기기의 물리적 RAM 용량을 기준으로 이미지 캐시 사이즈를 동적으로 결정하는 방식을 적용

왜 동적 설정이 필요할까?

iOS는 앱이 사용할 수 있는 메모리 한도를 초과하면 명시적인 에러 없이 프로세스를 종료할 수 있음.

저사양 기기의 경우

RAM 2GB 기기에서 캐시를 1GB로 고정하는 것은 실제 사용 가능한 메모리 대비 과도한 점유가 될 수 있음.
경우에 따라서는 결과적으로 메모리 부족으로 인한 크래시 확률이 높아짐.

고사양 기기의 경우

이미지 디스크 접근 증가
네트워크 재요청 증가
이미지 디코딩 비용 증가
스크롤 체감 성능 저하

즉, 캐시를 너무 작게 잡아도 손해가 커서 기기별 메모리 특성에 맞게끔 균형을 찾고자 함.

전체 코드

메모리 캐시 사이즈에 기기별 가용 가능한 메모리 크기를 기반으로 상한값을 다르게 설정.
pyshicalMemory는 기기 스펙의 메모리 용량과 일치하지 않음.

아래 코드에서 1/8 값을 사용하고 있으나 프로젝트 특성에 맞게 변경해도 됨.
- 안드로이드 공식 문서에서 1/8 사용하고 있는 예제가 있어서 그대로 적용

private func configureImageCacheLimits() {
        // 기기의 물리적 RAM 전체 용량 (단위: bytes)
        // 예) 6GB RAM → 6,442,450,944 bytes
        let physicalMemory = ProcessInfo.processInfo.physicalMemory
        // 이미지 캐시에 허용할 최소 메모리 한도 (단위: MB)
        let minimumLimitMB: UInt64 = 100
        
        // 이미지 캐시에 허용할 최대 메모리 한도 (단위: MB)
        let maximumLimitMB: UInt64 = 512
        
        // physicalMemory(bytes) → MB 변환 과정:
        //   ÷ 8          : 전체 RAM의 1/8만 캐시에 사용 (나머지는 OS or 앱 등이 사용)
        //   ÷ 1024       : bytes → KB
        //   ÷ 1024       : KB → MB
        //
        // 예) 6GB RAM 기기:
        //   6,442,450,944 ÷ 8 = 805,306,368 bytes (약 768MB, RAM의 1/8)
        //   805,306,368 ÷ 1024 = 786,432 KB레
        //   786,432 ÷ 1024 = 768 MB
        //   → min(512, 768) = 512 → max(100, 512) = 512MB 적용
        //
        // 예) 2GB RAM 기기:
        //   2,147,483,648 ÷ 8 = 268,435,456 bytes (약 256MB)
        //   → 256MB → max(100, 256) = 256MB 적용
        let computedLimitMB = max(
            minimumLimitMB,
            min(maximumLimitMB, physicalMemory / 8 / 1024 / 1024)
        )
        
        // 최종 캐시 한도를 다시 bytes로 변환 (SDImageCache에 bytes 단위로 전달해야 하므로)
        // 예) 512MB → 512 × 1024 × 1024 = 536,870,912 bytes
        let physicalMemoryMB = physicalMemory / 1024 / 1024
        let physicalMemoryGB = physicalMemoryMB / 1024
        
        var systemInfo = utsname()
        uname(&systemInfo)
        let deviceModel = withUnsafePointer(to: &systemInfo.machine) {
            $0.withMemoryRebound(to: CChar.self, capacity: 1) {
                String(validatingUTF8: $0) ?? "Unknown"
            }
        }
        
        print("기기 모델: \(deviceModel)")
        print("물리 메모리: \(physicalMemoryGB) GB")
        print("캐시 한도: \(computedLimitMB) MB")
    }

아이폰 15 Pro

아이폰 13 mini

아이폰 13 미니

기기	RAM	1/8 계산값	최종 적용
iPhone SE (1st)	2GB	256MB	256MB
iPhone 11	4GB	512MB	512MB
iPhone 15 Pro	6GB	1024MB	512MB (상한 제한)

(참고)
https://developer.android.com/topic/performance/graphics/cache-bitmap?hl=ko

비트맵 캐싱 | App quality | Android Developers

단일 비트맵을 사용자 인터페이스(UI)에 로드하는 것은 간단하지만 한 번에 더 큰 이미지의 집합을 로드해야 하면 더 복잡해집니다. 많은 경우(ListView, GridView 또는 LruCache 클래스와 같은 구성요소

developer.android.com

HTTPURLResponse.allHeaderFields 파싱 시 NSNumber 헤더 누락 문제

lgvv — Wed, 4 Feb 2026 02:13:19 +0900

HTTPURLResponse.allHeaderFields 파싱 시 NSNumber 헤더 누락 문제

네트워크 응답 처리 레이어에서 `HTTPURLResponse.allHeaderFields`를 [String: String] 형태로 변환해 상위 모듈에 전달.

기존 변환 사용 로직은 Any를 `as? String`으로 캐스팅하는 방식인데, 이 방식이 Swift 타입 시스템과 Foundation의 NSNumber 브리징 동작이 결합되어 일부 헤더를 조용히 누락시키는 현상

코드 예시

참고로 헤더에는 동일한 key가 중복을 허용하고 있어서 header는 동일 키 값에 대해서도 여러개 받을 수 있도록 해야함.

/// ❌ 기존 코드 
var responseHeader: [String: String] = [:]

for (headerKey, headerValue) in httpResponse.allHeaderFields {
    guard let key = headerKey as? String,
          let value = headerValue as? String   // ← ❌ NSNumber면 nil → continue
    else { continue }

    responseHeader[key] = value
}

/// ✅ 안전한 방식
var responseHeader: [String: String] = [:]

for (key, value) in httpResponse.allHeaderFields {
    guard let keyString = key as? String else { continue }
    responseHeader[keyString] = String(describing: value)
}

///   NSNumber가 데이터로 들어오는 경우 
Content-Length: 123

(참고)

https://developer.apple.com/documentation/foundation/httpurlresponse/allheaderfields

allHeaderFields | Apple Developer Documentation

All HTTP header fields of the response.

developer.apple.com

https://developer.apple.com/documentation/foundation/httpurlresponse/value(forhttpheaderfield:)

HTTPURLResponse | Apple Developer Documentation

The metadata associated with the response to an HTTP protocol URL load request.

developer.apple.com

https://developer.apple.com/documentation/swift/string/init(describing:)-67ncf

init(describing:) | Apple Developer Documentation

Creates a string representing the given value.

developer.apple.com

https://github.com/swiftlang/swift-corelibs-foundation/pull/287

Implement NSHTTPURLResponse by danieleggert · Pull Request #287 · swiftlang/swift-corelibs-foundation

This implements both the trivial attributes (statusCode and allHeaderFields), and also parses the headers in order to set the following attributes: public var mimeType: String? { get } public var e...

github.com

빠르게 링크: 빌드 및 실행 시간 개선 (Link fast: Improve build and launch times) - WWDC22

lgvv — Fri, 2 Jan 2026 17:06:50 +0900

빠르게 링크: 빌드 및 실행 시간 개선 (Link fast: Improve build and launch times) - WWDC22

What is static linking?
- 몇 가지 예와 정적 링킹이 무엇인지 정의
Recent ld64 improvements
- 애플의 정적 링커인 ld64의 신기능
Sattic linking best practices
- 정적 링킹에 대한 배경시직과 함께 모범 사례에 대해서 설명
What is dynamic linking?
- 동적 링킹 과정에서 어떤 일이 발생하는지 다룸
Recent dyld improvements
- 올해 dyld의 새로운 기능
Dynamic linking best practices
- 동적 링크 시간 성능 개선을 위해 할 수 있는것
New tools
- 바이너리에 무엇이 있고, 동적 링킹 과정에서 어떤 일이 일어나는지 확인

라이브러리나 프레임워크의 형태로 우리 코드가 다른 라이브러리의 코드를 사용하려면 링커가 필요함.

링킹에는 두가지 유형이 존재

정적 링킹 (static linking)
- 앱을 빌드할 때 발생
- 앱을 빌드하는데 걸리는 시간과 앱의 최종 크기에 영향
동적 링킹 (dynamic linking)
- 앱이 실행될 때 발생
- 앱이 작동할 때까지 사용자의 대기 시간에 영향을 줄 수 있음.

초기에는 프로그램들이 간단했고, 소스 파일도 하나 뿐이라서 단 하나의 소스 파일 에서 컴파일러를 실행하면 실행 가능한 프로그램을 생성하지만 하나의 소스파일만 가지고는 프로그램을 확장하기가 쉽지가 않음.

여러 파일을 컴파일 하기 위해서 처음에는 컴파일러를 여러개로 나누는 방향으로 접근.

오브젝트 파일을 읽고 실행 가능한 파일로 연결하는 링커를 정적 링커 `ld`라고 부름.

소프트웨어가 더 많이 발전하면서 사람들은 .o 파일들을 주고 받게 됨.

.o 파일이 늘어마녀서 사람들이 묶어서 제공하자고 함.

처음에는 파일 묶는 아카이브 도구 ('ar')을 사용 (백업 및 배포에 사용)

따라서 워크플로우가 위와 같이 바뀜.

여러개의 .o 파일을 하나의 아카이브로 'ar'화 하고 아카이브 파일에서 직접적으로 .o 파일들을 읽도록 링커가 향상됨.

당시에는 라이브러리 또는 아카이브라고 불렀음. (오늘날에는 정적 라이브러리라고 부름)

하지만 라이브러리의 수천개의 함수가 프로그램에 복사되었기 때문에 최종 프로그램이 무거워짐.

최적화가 필요했고, 링커가 정적 라이브러리의 모든 .o 파일을 사용하는 대신 정의되지 않은 심볼 문제가 해결되는 경우의 .o 파일만 정적 라이브러리에서 가져옴.

모든 C 표준 라이브러리 함수를 포함하는 거대한 하나의 lib.a 정적 라이브리러를 구축할 수 있음을 의미.

모든 프로그램이 하나의 libc.a에 연결할 수 있지만, 각 프로그램은 실제로 필요로하는 libc의 일부만 가져옴.

오늘날에도 이 모델은 존재.

하지만 정적 라이브러리의 선택적 로딩은 분명하지 않고 개발에 있어서 어려움에 빠지기도 함.

정적 라이브러리의 선택적 로딩을 좀 더 명확히 하기 위한 간단한 시나리오를 알아보고자 함.

각각을 .o 파일을 컴파일하면, 위의 이미지처럼 생성되고 회색 박스가 아닌 부분은 정의되지 않은 함수이기 때문이며 심볼의 사용이지 정의를 의미하는 것이 아님.

1, 2번의 플로우

bar.o와 baz.o를 정적 라이브러리 하나로 합치며, 두개의 .o파일과 이 정적 라이브러리를 링크.

실제로 일어나는 일을 순서대로 알아보자.

1. 링커는 명령어 라인 순서대로 파일을 읽어나감.
- 가장 먼저 찾은건 main.o이고, main.o를 로드하고 심볼 테이블에 보이는 main대한 정의를 찾음.
- 하지만 main 안에 정의되지 않은 foo가 있다는 것도 찾음.
2. 그 다음 링커는 명령어 라인의 다음 파일 foo.o를 파싱.
- 이 파일은 foo에 대한 정의를 추가하며 즉, 더 이상 정의되지 않은 foo가 아닌 것.
- 하지만 foo.o의 로드는 정의되지 않은 새 심볼 bar또한 추가
- 명령어 라인의 모든 .o파일이 로드되어서 링커는 정의되지 않은 심볼이 남아 있는지 확인
- 이 경우 아직 'bar'가 정의되지 않았기 때문에 링커는 명령어 라인의 라이브러리들을 살펴보면서 정의되지 않은 'bar' 심볼을 충족하는 라이브러리를 찾음
- 링커가 정적 라이브러리 bar.o에서 'bar' 심볼이 정의되는 것을 찾음
- 따라서 링커는 아카이브(libbarbaz.a)로 부터 bar.o를 로드
- 이 시점에서는 더 이상 정의되지 않은 심볼이 없어서 따라서 라이브러리에서 찾기를 중단

3. 링커는 다음 단계로 이동해 프로그램에 포함 될 모든 함수와 데이터에 주소를 할당
- 모든 함수와 데이터를 출력 파일에 복사하여 출력 프로그램을 완성
- baz.o는 정적 라이브러리에 있지만, 프로그램에는 로드되지 않음.
- 링커가 정적 라이브러리에서 선택적으로 로드한 방식 때문에 로드되지 않음.
- 이 방식은 분명하진 않아도 정적 라이브러리의 핵심적인 측면.

여기까지가 정적 링킹 및 정적 라이브러리의 기본과 이해.

ld64 최적화에 많은 시간을 들여서 링커는 많은 프로젝트에서 2배 더 빠름.

링커 작업을 병렬로 수행하도록 여러개의 코어를 사용할 수 있는 여러 영역을 찾음

입력 파일의 내용을 출력 파일로 복사
lINKEDIT의 부분을 병렬 구축
UUID 계산을 변경하고 코드 서명 해시를 병렬로 수행하는 것도 포함
여러 알고리즘을 개선
- 각 심볼의 문자열 슬라이스를 나타내는데 C++의 string_view 객체를 사용하게 되면 exports-trie builder가 굉장히 잘 작동하는 것을 볼 수 있음.
바이너리의 UUID를 계산할 때 최신 암호화 라이브러리를 사용해 하드웨어 가속을 활용
다른 알고리즘 개선도 존재

링커의 성능 개선 작업 동안 일부 앱에서 링크 시간에 영향을 미리는 구성 문제를 발견.

우리 프로젝트에서 링크 시간 개선을 위해 할 수 있는 다섯 가지 주제를 다룸.

1. 정적 라이브러리의 사용 여부
2. 링크 시간에 큰 영향을 주는 세가지 옵션 (잘 알려지지 않음)
- `-all_load` or `-force_load`
- `-no_exported_symbols`
- `-no_deduplicate`
3. 정적 링크의 속성

1. 정적 라이브러리에 빌드되는 소스 파일에 열심히 작업해서 빌드 시간이 느려지는 경우
- 파일이 컴파일 되고 나면 목차를 포함한 정적 라이브러리 전체를 다시 빌드해야 하기 때문에 이런 현상이 발생
  - 단지 추가적인 I/O가 많아지는 것
- 안정적인 코드에는 정적 라이브러리그 가장 적합
  - 코드가 활발하게 변경되지 않는 경우
- 빌드 시간을 줄이기 위해서는 현재 개발 중인 코드를 정적 라이브러리 밖으로 이동하는 것을 고려

2. 아카이브에서 선택적으로 로딩하는 것을 확인했는데, 선택적 로딩의 단점은 링커가 느려진다는 것
- 왜냐하면 빌드를 재현 가능하도록 하면서 전통적인 정적 라이브러리의 의미를 따르기 위해서는 링커가 라이브러리를 고정된 직렬 순서로 처리해야 하기 때문
  - 즉, ld64의 병렬화 이점을 정적 라이브러리와 함께 사용할 수 없다는 것
- 이런 기록하는 동작이 별로 필요하지 않은 경우라면 링커 옵션을 사용해 빌드 속도를 높일 수 있음.

링커 옵션 `-all_load`
- 모든 정적 라이브러리의 모든 .o 파일을 로드하도록 링커에 지시
- 이는 앱이 선택적 로딩을 하지만 결국 모든 정적 라이브러로부터 대부분의 콘텐츠를 로드하는 경우라면 유용
- `-all_load`의 사용은 링커가 모든 정적 라이브러리와 해당 콘텐츠를 병렬로 파싱할 수 있도록 함.
- 동일한 심볼을 구현하는 여러 정적 라이브러리가 있어서 명령어 라인의 정적 라이브러리 순서에 의존해 어떤 구현을 사용할지 정하는 방식이라면 이 옵션은 적합하지 않음.
  - 링커가 모든 구현을 로드하기 때문에 일반 정적 링킹 모드에서 찾을 수 있는 심볼의 의미를 가져오리란 법이 없기 때문.
- `-all_load`의 또 다른 단점은 프로그램이 무거워 질 수 있다는 것 `unused` 코드가 계속 추가되기 때문.
  - 이를 보완하기 위해서 `-dead_strip` 링커 옵션을 사용할 수 있음
    - 이 옵션으로 연결 불가한 코드와 데이터를 링커가 제거
    - `-dead_strip` 알고리즘은 빠르게 출력 파일의 사이즈를 줄임으로써 자체적으로 크기를 절약
    - `all_load`, `dead_strip`를 함께 사용한다면 이들 옵션의 유무에 따른 링커 시간을 측정해서 우리 케이스에 유리한 선택인지 확인해야 함

링커 옵션 `-no_exported_symbols`
- 링커가 생성하는 LINKEDIT 세그먼트의 한 부분은 하나의 exported-trie로 preix trie(접두사 트리)이며 내보낸 모든 심볼 이름, 주소 및 플래그를 인코딩 함.
- 모든 dylib에는 내보낸 심볼이 있어야 하는 반면 메인 앱 바이너리는 일반적으로 내보낸 심볼이 필요하지 않음.
  - 즉, 일반적으로 메인 실행 파일에서는 심볼을 조회하지 않음.
  - 이런 케이스에 `-no_exported_symbols`를 사용하여 앱 타겟에 대해 LINKEDIT에서 trie 데이터 구조 생성을 건너뛰도록 할 수 있음.
    - 따라서 링크 시간이 개선됨.
- 메인 앱 실행 파일로 다시 연결되는 플러그인을 로드하거나 xctest 번들 실행을 위해 호스트 환경으로 앱과 xctest를 사용하면 앱에 exports가 있어야 함.
  - 즉, 해당 구성에서는 `-no_exported_symbols`를 사용할 수 없다는 것
- 사이즈가 큰 경우엔 exports trie의 억제가 합리적임.
  - dyld_info 명령을 실행하여 내보낸 심볼의 수를 계산할 수 있음
- 해당 옵션을 통해 링커가 해당 심볼 수에 대한 exports trie를 빌드하는데 시간을 단축할 수 있음.

링커 옵션 `-no_deduplicate`

명령은 같지만 이름이 다른 함수를 병합하기 위해서 새로운 패스를 추가
- C++의 템플릿 확장으로 그런 함수들을 많이 얻음.
알고리즘은 비싸며 중복을 찾기 위해서 링커는 모든 함수의 명령을 반복적으로 해시해야 하기 때문
- 비용 문제 때문에 링커가 weak-def된 심볼만 살펴보도록 알고리즘을 제한함
- 템플릿 확장으로 C++ 컴파일러가 내보내는 인라인 되지 않은 것들을 제한.
de-dup 중복 제거는 사이즈 최적화로 디버그 빌드는 사이즈가 아닌 속도 빠른 빌드에 관함.
- Xcode는 디버그 구성을 위해 링커에 `-no_deduplicate`를 전달해 de-dup 최적화를 비활성화 함
clang 링크 라인을 `-O0`으로 실행할 경우 no-dedup 옵션을 링커에 전달.
요약하자면 C++를 사용하고 custom build system를 가진 경우 링크 시간 개선을 위해서 디버그 빌드가 `no_dedeuplcate`를 추가하도록 해야함.
- Xcode에서 비표준 구성을 사용하거나 다른 빌드 시스템을 사용하는 경우

Xcode Build Settings > Other Linker Flags에서 변경할 수 있음.

`all_load`, `-Wl`, `-no_exported_symbols`, `no_deduplicate` 등이 존재

정적 라이브러리에 소스 코드가 빌드되고 앱이 이 라이브러리에 연결되지만 해당 코드는 최종 앱에 포함되지 않음.
- 예를 들어 어떤 함수에 `__attribute__((used))`를 추가했다거나 Objective-C 카테고리가 있는 경우 링커가 선택적 로딩을 수행하기 때문에 정적 라이브러리에 있는 .o 파일이 링크 과정 중에 필요한 일부 심볼 또한 정의하지 않는다면 해당 .o 파일은 링커가 로드하지 않게 됨.
정적 라이브러리와 `Dead stripping`간의 상호작용도 흥미로운데, 정적 라이브러리의 문제를 숨길 수 있음.
- 일반적으로 심볼의 누락이나 중복되는 심볼은 링커의 오류를 유발
- 하지만 `Dead stripping`은 링커가 메인에서 시작해서 모든 코드와 데이터에 걸쳐 도달 가능한 패스를 실행하도록 해서 심볼의 누락이 연결할 수 없는 코드에서 온 것으로 판명되면 링커가 심볼 누락 오류를 억제하도록 만듦.
- 유사하게 정적 라이브러리에 중복되는 심볼이 있는 경우에 링커는 첫번째 것을 선택하고 오류를 내뱉지 않음
정적 라이브러리를 사용할 때 하나의 정적 라이브러리가 여러 프레임워크에 통합되는 경우 각각의 프레임워크는 개별적으로는 잘 실행되지만 어느 시점에서 일부 앱은 두 가지 프레임워크를 모두 사용하게 되고 이는 런타임에 문제를 발생시킴.
- 가장 흔한 경우는 Objective-C 런타임 경고이며 동일한 클래스 명의 여러 인스턴스에 대한 경고.
- 종합적으로 정적 라이브러리는 강력하며 이러한 위험을 피하기 위해서는 정확한 이해가 필요.

정적 라이브러리와 정적 링킹에 대한 다이어그램 먼저 살펴보자.

시간이 지나면서 이 다이어그램이 확장될 것을 생각해보면 점점 더 많은 소스코드가 생김.

사용할 수 있는 라이브러리가 점점 많아질수록 최종 프로그램의 크기가 커짐.

시간에 따라 해당 프로그램 빌드에 들어가는 정적 링크 시간도 증가.

'ar'에서 'ld'로 변경

'ar'에서 'ld'로 바꾼다면 출력 라이브러리는 이제 실행 가능한 바이너리가 됨.

'ar'에서 'ld'로 바꾸는 것이 90년대 동적 라이브러리의 시작.

약칭으로 동적 라이브러리를 'dylibs'라고 함.

다른 플랫폼에서는 'DSO'(Dynamic Shared Objects), 'DLL(Dynamic-Link Library)'이라고 부름.

핵심은 정적 링커가 동적 라이브러리와의 링킹을 다르게 취급한다는 점.

라이브러리에서 최종 프로그램으로 코드를 복사하는 것 대신 링커가 일종의 Promise를 기록함.

동적 라이브러리에서 사용되는 심볼 및 런타임 시 라이브러리의 경로를 기록하는 것.

이것의 장점으로는 프로그램 파일 사이즈가 개발자의 통제 하에 있을 수 있게 됨.

즉, 우리가 작성한 코드와 런타임에 필요한 동적 라이브러리 목록만 포함됨.

라이브러리 코드의 복사본을 더 이상 프로그램에 받지 않게 됨.

프로그램의 정적 링크 시간은 이제 코드 크기에 비례하고 링크하는 dylib 수와는 무관함.

이로 인해서 또한 가상 메모리 시스템을 활용할 수 있음.

여러 프로세스에서 동일한 동적 라이브러리가 사용되는 경우 가상 시스템은 그 dylib를 사용하는 모든 프로세스에서 해당 dylib에 대해 동일한 물리적 RAM 페이지를 재사용함.

여기까지가 동적 라이브러리의 시초와 이를 통해 해결한 문제를 같이 확인함.

동적 라이브러리의 이점

동적 라이브러리 사용의 이점은 빌드 시간 단축

동적 라이브러리의 비용

1. 앱 시작 속도의 둔화
- 앱 시작시 프로그램 파일 하나만 로드하는 것이 아니기 때문
- 모든 dylib들이 로드되고 함께 연결되어야 함.
- 빌드 시간에서 시작 시간으로 링킹 비용의 일부를 전가.
2. 동적 라이브러리 기반의 프로그램은 더티 페이지가 더 많음.
- 정적 라이브러리의 경우 모든 정적 라이브러리의 모든 부분들을 링커가 메인 실행 파일의 동일한 DATA 페이지에 다 같이 배치
- 하지만 dylib를 사용하면 DATA페이지가 각 라이브러리에 있음.
3. dyld라는 동적 링커가 필요함.
- 빌드 시에 실행 파일에 기록된다던 Promise 부분에서 라이브러리를 로드하기 위해 Promise를 처리할 무언가가 런타임에 필요하기 때문

이것이 바로 dyld 동적 링커의 용도임.

동적 링킹이 런타임에서의 동작

1. 실행 가능한 바이너리는 세그먼트로 분할
- 일반적으로 최소한 TEXT, DATA, LINKEDIT 으로 분할.
- 세그먼트는 항상 OS 사이즈의 배수로 각 세그먼트는 다른 권한을 가짐
- 예를 들어 TEXT는 '실행' 권한을 가짐
- CPU가 페이지의 바이트를 기계 명령어로 처리 가능함을 의미.
2. 런타임 시 dyld는 여기 보이는 것처럼 각 세그먼트의 권한을 받아 실행 파일들을 메모리에 mmap() 해야 함.
- 세그먼트들은 페이지 사이즈이고 페이지 정렬되기 때문에 가상 메모리 시스템이 프로그램이나 dylib 파일을 VM 범위의 백업 저장소로 설정하는 것이 간단함.
- 즉, 해당 페이지에 메모리 접근이 있을때 까지 RAM에 아무것도 로드되지 않으며 이로 인해 페이지 폴트가 발생하고 이는 VM 시스템이 파일의 적절한 하위 범위를 읽고 그 콘텐츠로 필요한 RAM 페이지를 채우도록 만듦.
- 하지만 매핑만으로는 충분하지 않고 어떻게든 프로그램은 연결(link)되거나 dylib에 바인딩되어야 하는데, 이를 위해서 'fix ups'이란 개념이 존재함.

TEXT, DATA, LINKEDIT으로 구성된 mach-o 파일을 보자

TEXT는 불변이며, 코드 서명을 기반으로 하는 시스템 안에 있어야 함.

malloc의 상대주소는 프로그램이 빌드될 때 알 수 없고, 일어나는 일은 malloc이 dylib에 있는 것을 보고 정적 링커가 호출 사이트를 변환

이때 동일한 TEXT 세그먼트의 링커에 의해서 호출 사이트는 스텁에 대한 호출이 됨.

따라서 빌드시에 상대 주소가 알려지고 이는 bl 명령어가 올바르게 형성될 수 있음을 의미

이로인해서 스텁이 DATA로 부터 포인터를 로드하고 해당 위치로 점프함.

즉, 런타임에서는 TEXT에 대한 변경이 필요하지 않음.

dyld에 의해 DATA만 변경됨.

dyld를 이해하는데 중요한 것은 dyld에 의한 모든 수정이 단지 DATA에 대한 dyld의 포인터 설정 뿐이라는 것.

Rebases, Binds

dyld가 수행하는 수정사항에 대해 더 자세히 보자면 LINKEDIT 어딘가에 수정 작업에 써야하는 정보가 있음.

'fixups'에는 두가지 유형이 존재.

첫번째 유형은 Rebases
- dylib 또는 app 자체 내에서 가리키는 포인터를 갖는 경우.
- ASLR이라는 보안기능이 존재하는데 dyld가 임의의 주소에서 dylib를 로드하도록 만듦.
- 따라서 내부 포인터는 빌드 시에 설정할 수 없으며, 이런 포인터들은 시작 시에 dyld가 조정하거나 'Rebases'를 해야 함.
- dylib가 주소 0에서 로드되는 경우에 디스크에서 이런 포인터들은 target address들을 포함함.
- 따라서 LINKEDIT이 기록해야 하는건 각 'Rebases'의 위치가 전부임.
- dyld는 dylib의 실제 로드 주소를 각 'Rebases' 위치에 추가해 올바르게 수정할 수 있음.
두번째 유형은 Binds
- 'Binds'는 symbolic reference로 target이 숫자가 아닌 symbol 이름.
- 'malloc' 함수에 대한 포인터를 예로 하자면, 문자열 '_malloc'는 실제로 LINKEDIT에 저장되며, dyld는 해당 문자열을 사용해 libSystem.dylib의 exports trie에서 mallo의 실제 주소를 조회
- 그 다음 dyld는 해당 값을 'Binds'가 지정한 위치에 저장

WWDC22에서는 fixups을 인코딩하는 새로운 방법으로 'chained fixups'을 새롭게 발표.

'chained fixups'의 첫번째 장점은 LINKEDIT이 더 작아짐.
- 모든 수정 위치를 저장하는 대신 새 형식은 각 DATA 페이지의 첫번째 수정 위치와 가져온 심볼 목록만을 저장하기 때문.
- 나머지 정보는 최종적으로 'fixups'이 고정될 위치인 DATA 세그먼트 자체에 인코딩.
- 'fixups' 위치가 서로 연결되어 있기 때문에 'chained fixups'이라고 명명함
- LINKEDIT은 첫번째 수정이 있었던 위치만 알려주고 DATA의 64bit 포인터 위치에 있는 일부 비트들은 다음 'fixups' 위치에 대한 오프셋을 포함함
- 이 안에 fixups이 'Binds'인지 'Rebases'인지 알려주는 bit도 들어있음.
- 'Binds'의 경우 나머지 bit는 심볼의 인덱스가 됨.
- 'Rebases'의 경우 나머지 bit는 이미지 내 target에 대한 오프셋이 됨.
- 'chained fixups'에 대한 런타임 지원은 iOS 13.4이상부터 존재.

chained fixups을 제대로 이해하기 위해서는 dyld가 작동하는 방식에 대해서 알아야 함.

dyld는 메인 실행 파일에서 시작.

앱이라고 가정하면 mach-o를 파싱하여 종속 dylib들을 찾는데, 필요한 동적 라이브러리를 찾는 것.
해당 dylib들을 찾아 mmap()을 수행.
그 다음 이들 각각에 대해 재귀적으로 mach-o 구조를 파싱하는데 필요에 따라 추가적으로 dylib를 로드하면서 진행함.
모든 것이 로딩되면 dyld는 필요한 모든 'Binds' 심볼을 조회하고 fixups을 수행할 때 해당 주소를 사용
모든 fixups이 완료되면 dyld는 이니셜라이저를 상향식으로 실행.

애플은 5년전에 이를 발표했으며 프로그램과 앱이 실행될 때마다 녹색 단계들이 매번 동일.

dylib들이 변경되지 않는 한 모든 녹색 단계는 첫번째 실행에서 캐시되고 후속 실행에서는 재사용 될 수 있음.

WWDC22에서는 dyld의 새로운 속성으로 Page-in linking을 발표.

dyld가 모든 fixups을 실행시에 모든 dylib에 적용하는 대신 커널이 fixups을 DATA 페이지에 lazy하게 적용할 수 있음.
mmap() 처리된 영역의 일부 페이지에서 일부 주소를 처음 사용하면 커널이 해당 페이지를 읽도록 유발하는 경우가 항상 있었음.
그러나 이제 DATA 페이지의 경우 커널은 해당 페이지에 필요한 fixup도 적용함.
10년이 넘게 dyld 공유 캐시에 있는 OS dylib에 대한 page-in linking 특수 케이스가 존재했었음.
WWDC22부터는 이를 일반화하여 모든 사람들이 사용할 수 있도록 만듦
- 이 매커니즘은 더티 메모리와 실행 시간을 줄임.
- 이는 DATA_CONST 페이지가 깨끗하다는 의미이고 TEXT 페이지처럼 축출과 재생성이 가능해서 메모리 압박이 줄어듦
Page-in linking은 chained-fixups로 빌드된 바이너리에만 작동.
- 왜냐하면 chained-fixups을 사용하면 대부분의 fixups 섲정보가 디스크의 DATA 세그먼트에 인코딩되고 Page-in linking 중에 커널에서 사용할 수 있기 때문
- 주의할 것은 dyld가 이 매커니즘을 launch 중에만 사용한다는 것.
- 나중에 dlopen()된 dylib들은 Page-in linking되지 못하는데, 이 경우에는 dyld는 전통적인 경로를 사용하고 fixups을 dlopen 호출 중에 적용

기존 dyld 워크플로우 다이어그램으로 돌아가자면 첫 실행에서 작업을 캐싱하고 후행 실행에서 이를 재사용함으로써 최적화하는 방향으로 진행.

2022년 이후에는 apply fixups 단계에서 fixups를 직접 수행하지 않고 lazy하게 Page-in 단계에서 커널이 하도록 만들어서 최적화 할 수 있음

동적 링킹의 모범 사례에 대해서 알아보고자 함.

즉, 동적 링크의 성능 개선을 위해 가능한 것 중에서는 기존에 dyld는 이미 동적 링킹의 많은 부분을 최적화 함.

따라서 우리가 제어할 수 있는건 dylib의 수임.

더 많은 dylib가 있을수록 dyld가 더 많은 로드 작업을 수행해야 하므로 더 적은 dylibs를 사용하면 더 적은 로드 작업을 수행할 수 있음.
정적 이니셜라이저를 사용하여 최적화 할 수 있는데, 정적 이니셜라이저에서는 I/O 또는 네트워킹을 수행하지 말 것.
- 몇 밀리초 이상 소요될 수 있는 작업은 이니셜라이저에서 수행되어서는 안됨.
세상이 점점 복잡지고 요구사항이 늘어나면서 코드를 라이브러리로 관리하는게 합리적.
- 목표는 동적 및 정적 라이브러리 사이의 최적의 지점을 찾는 것.
- 너무 많은 정적 라이브러리와 반복적인 빌드/디버그 사이클은 늦어짐.
- 반면에 너무 많은 동적 라이브러리와 느린 시작 시간은 사용자가 알아차릴 수 있음.
- WWDC22 이후로는 ld64의 속도를 높였기 때문에 최적의 지점이 변경되었을 수도 있음.
더 많은 정적 라이브러리 또는 더 많은 소스 파일을 앱에서 직접 사용하면서 여전히 동일한 시간에 빌드할 수 있음.

링킹 과정을 들여다보는 데 도움이 될 새로운 도구 2가지 발표.

dyld_usage
- dyld가 하는 일을 추적할 수 있음.
- macOS만 실행할 수 있거나 시뮬레이터에서 앱 실행을 추적하거나 앱이 Mac Catalyst 용으로 빌드된 경우에 사용할 수 있음.

dyld_info
- 이를 사용해 디스크와 현재 dyld 캐시 모두에서 바이너리를 검사할 수 있음.
- 이 도구에는 많은 옵션이 있지만 export 및 fixups을 보는 방법이 있음.
- -fixups 옵션은 dyld가 처리할 모든 fixups 위치와 그 타겟을 표시함.
- 파일이 이전 스타일의 'fixups'이든 새로운 'chained-fixups'이든 관계없이 출력은 동일함.
- -exports 옵션은 dylib에 있는 모든 내보내진 심볼 및 dylib의 시작 부분의 각 심볼에 대한 오프셋을 표시함.
- 이 경우 dyld 캐시에 있는 dylib인 Foundation.framework에 대한 정보를 보여줌.
- 디스크에 파일이 없지만 dyld_info 도구는 dyld와 동일한 코드를 사용하므로 찾을 수 있음.

동적 라이브러리와 정적 라이브러리이 역사와 절충 과정을 해당 내용을 통해 이해했으니 우리 앱이 수행하는 작업을 검토해보고 그 최적의 지점을 찾았는지 판단해봐야 함.

앱이 대형인데 빌드가 링크하는데 시간이 꽤 오래 소요된다면 더 빠른 링커가 있는 Xcode를 사용하거나
여전히 정적 링크의 속도도 높이고 싶다면 세가지 링커 옵션을 살펴보고 우리 앱 빌드에서 유의미한 링크 시간 개선이 있는지 확인해보기.
iOS 13.4 이상에서는 `chained-fixups`를 활성화하여 앱 및 임베디드 프레임워크 빌드해 볼 수 있음.
그 다음이 iOS 16에서 더 작고 더 빠르게 실행되는지 확인

(링크)

https://www.youtube.com/watch?v=yLXGtXNYhdg

Xcode 빌드에서의 병렬 처리에 대한 오해 해소(Demystify parallelization in Xcode builds) - WWDC22

lgvv — Tue, 30 Dec 2025 21:18:18 +0900

Xcode 빌드에서의 병렬 처리에 대한 오해 해소(Demystify parallelization in Xcode builds) - WWDC22

Xcode의 빌드 프로세스에 대해 자세히 정리

Core concepts
- 빌드의 핵심 개념 및 빌드 성능 문제를 검토하는데 도움이 되는 Xcode 도구 탐색
Build phase
- 타겟 빌드 시 Xcode의 병렬화 증가 방법
Corss-Target builds
- Xcode가 어떻게 많은 타겟으로 구성된 프로젝트를 구축하면서 빌드를 전체적으로 병렬로 처리하는지

Xcode의 빌드 시스템은 전체 프로젝트의 표현으로 호출.

모든 source file, assets, build configuration 등 실행 타겟과 같은 기타 구성을 포함.

빌드 시스템은 앱 빌드 방법에 대한 단일 정보 소스로 어떤 설정을 사용하여 어떤 도구를 호출할 지 최종적으로 앱을 만들기 위해 어떤 중간 파일을 생성할 지 알고 있음.

다음 단계로 빌드 시스템은 컴파일러와 같은 프로젝트의 입력 파일을 처리하는 도구를 호출.

Clang과 Swift 두 컴파일러 모두 링커가 앱을 나타내는 실행 프로그램을 연결하는 데 필요한 오브젝트(.o) 파일을 생성.

Swift 컴파일러
- 입력 소스 파일을 사용해서 사용자의 의도를 캡처하고 실행 가능한 바이너리(기계어)로 변환하여 오류가 있는지 소스 코드를 확인.
- 이 프로세스는 실패할 수 있고 실패 시 빌드가 취소되지만, 성공할 경우 각 입력에 대한 오브젝트(.o) 파일을 생성
오브젝트 파일
- 이 과정에서 오브젝트 파일은 링커를 호출하는데 사용.
링커
- 오브젝트 파일들을 결합하고 실행 파일을 생성하기 위해 외부에 연결된 라이브러리에 대한 참조를 추가

이 두 작업은 소비와 생산을 기반으로 종속성을 가짐.

컴파일러에 의해 생성된 오브젝트 파일은 링커에 의해 소비되며, 이로 인해서 빌드 시스템 그래프에 종속성이 만들어짐.

파일 콘텐츠 자체는 빌드 시스템에 중요하지 않지만 작업 간의 종속성은 중요.

빌드를 실행하는 동안에는 다른 작업의 입력을 생성하는 작업이 완료됐다는 확인이 되어야 해당 작업을 시작할 수 있음.

이 핵심 개념은 모든 종류의 작업에 유효

작업 A와 작업 B사이의 종속성을 보여주는 보다 일반적인 시각화 예시

해당 케이스의 경우에는 A는 B의 입력 중 일부 또는 전체를 생성.

컴파일링과 링킹은 전체 타겟을 빌드하기 위해 실행해야 하는 많은 작업 타입 중 일부일 뿐이므로 그래프에 좀 더 일반적인 작업을 추가.

에셋 컴파일링, 파일 복사 또는 코드 서명 같은 다른 타입의 작업(이미지의 Task C, Task D, Task E 등) 이들은 다함께 프레임워크 타겟의 빌드를 나타냄.

이러한 작업은 입력 및 출력을 기반으로 종속성을 정의.

따라서 Task A를 완료하면 Task B, C의 차단이 해제되고 Task B를 완료하면 Task D, E의 차단이 해제됨.

차단이 해제된 작업을 'donwstream'이라고 하며, 차단하는 작업을 'upstream'이라고 함.

많은 프로젝트에는 둘 이상의 프레임워크 타겟이 포함되므로 App과 App Extension을 나타내는 타겟으로도 확인해 보고자 함.

타겟은 프로젝트에서 서로 간의 종속성을 명시적 혹은 암시적 종속성을 통해 정의.

'Link Binary with Libraries' 빌드 단계에 추가되어 종속성을 정의하는 것과 같이 App은 Framework에 링크됨.

하지만, App Extension은 Framework와 종속 관계가 없음.

빌드 그래프를 실행할 때 서로 다른 작업엔 다른 시간이 걸리는데, 작업을 완료하는데 필요한 복잡성 수준으로 귀결됨.

입력의 크기와 필요한 계산에 따라 달라짐.

많은 파일의 컴파일링은 일반적으로 몇개의 헤더 파일 복사보다 훨씬 더 시간이 많이 걸림

이를 고려하면 위와 같은 이미지이며, 빌드 시스템이 같은 빌드를 실행할 때 종속성이 없는 작업을 먼저 실행하며 시작.

각각의 Task를 실행하면서 다운스트림 차단을 해제하면서 진행됨.

계획된 모든 작업이 완료될 때까지 이 프로세스를 따름.

다음 빌드에서는 입력이 변경되지 않는 작업은 빌드 시스템이 건너뛸 수 있음. (증분빌드)

변경된 입력으로 인해 Task를 다시 실행해야 하는 경우 다운스트림 작업도 재실행 해야함.

작업 실행의 종속성과 소요 시간은 첫 다운스트림 작업을 시작할 수 있는 시간을 말함.

따라서 이 정보를 사용하여 임계 경로를 계산할 수 있음.

이론적으로 무한한 리소스가 있을 때 빌드 실행에 필요한 가장 짧게 걸리는 시간을 의미.

해당 세션에서는 이 경로를 최적화해서 병렬화 및 확장성이 뛰어난 빌드 그래프를 생성하는 것을 알아봄.

더 짧은 임계 경로가 반드시 전체 빌드 시간을 단축하는건 아니지만, 빌드가 하드웨어와 함께 확장되도록 함.

빌드 임계 경로는 빌드 속도를 제한하는 요소들을 정의하며, 하드웨어에서 허용할지라도 빌드를 더 빨리 완료할 수 없음.

임계 경로 단축은 그 안에 있는 종속성을 분해하여 수행.

빌드가 어떻게 수행되었는지 살펴보고 그 빌드 실행에 대해 더 많은 이해를 하려면 실행 시간 기준의 데이터 플롯이 필요.

너비
- 작업의 길이를 나타냄.
높이
- 병렬로 처리되는 작업의 수를 나타냄. CPU와 메모리 사용률과 직결되진 않음.
빈 공간
- 다운스트림 작업을 막는 작업들로 인해 발생함.
색상
- 연관된 타겟

증분빌드에서는 실행된 작업만 포함되어서 오래 실행되는 작업을 발견할 수 있도록 도움.

특히, 이 빌드 중에 실행될 것으로 예상되지 않았을 수 있는 것들을 발견할 수 있도록 함.

해당 타겟의 실행 파일을 위해 성공적으로 빌드하기 위해 Xcode는 이 노드의 자식이 나타낸 모든 작업을 실행.

현재 빌드 로그에서 All로 되어 있으면 증분 빌드에서 다시 실행할 필요가 없던 이전 빌드의 작업도 표시됨.

하지만 Recent로 변경할 경우 실제로 실행된 작업만 표시되며, 건너 뛴 작업은 모두 숨겨짐.

이상적인 타임라인은 가능한 빈 공간이 적게 세로로 채워짐.

이렇게 하는 것이 빌드 그래프가 가장 잘 확장되고, 빌드가 빨라지며 이에 따라 하드웨어도 빨라짐.

Xcode가 개별 타겟을 정의하고 빌드하는 방법 및 병렬화를 증가시키는 방법에 대해서 살펴보고자 함.

타겟을 구성할 때, Build Phases는 해당 타겟의 제품 생산을 위해 수행해야 하는 작업을 설명.

컴파일 해야하는 에셋 및 헤더 또는 리소스와 같은 복사해야 하는 파일 그리고 링크되는 라이브러리나 실행되는 스크립트를 포함.

많은 빌드 단계는 다른 빌드 단계의 입출력 작업을 설명하며, 그들 사이에 종속성을 생성.

예를들어 타겟의 소스 파일은 링크되기 전에 컴파일이 되어야 함.

하지만 모든 빌드 단계에 적용되는 것은 아님.

각 빌드 단계의 작업들을 일렬로 실행하는 대신 빌드 시스템은 빌드 단계의 입력과 출력을 고려해 병렬로 실행이 가능한지 결정.

예를들어 컴파일과 리소스 복사는 병렬로 실행할 수 있는데, 왜냐하면 서로 다른 쪽의 출력에 의존하지 않기 때문임.

하지만, 링킹은 컴파일을 따라야 하는데, 왜냐하면 컴파일 단계에서 생성된 오브젝트(.o) 파일에 의존해야 하기 때문.

이번에는 'Run Script' 빌드 단계가 포함된 타겟을 확인.

다른 빌드 단계와 달리 스크립트 단계의 입출력은 Target Editor에서 수동으로 구성해야 함.

결과적으로 빌드 단계에서 데이터 경쟁이 발생하지 않도록 연속적으로 스크립트를 한번에 하나씩 실행.

만약 타겟의 스크립트가 종속성 분석을 기반으로 실행되고 입력 및 출력의 전체 목록을 지정하도록 구성된 경우

`FUSE_BUILD_SCRIPT_PHASES`를 YES로 설정하여 빌드 시스템이 병렬로 실행 시도를 해야함을 나타낼 수 있음.

스크립트를 병렬로 실행할 경우 빌드 시스템은 지정된 입력과 출력에 의존해야 함.

따라서 실행 단계에서 불완전한 입력 또는 출력 목록은 디버깅하기 어려운 매우 문제로 데이터 경쟁 문제로 나타날 수 있음.

Xcode는 사용자 스크립트 샌드박싱을 지원해 각 스크립트 단계의 종속성을 정확하게 선언할 수 있도록 함.

샌드박싱은 Shell Script가 실수로 소스파일 및 중간 빌드 객체에 접근하는 것을 차단하는 선택적인 기능.

이러한 항목이 명시적으로 선언되지 않는 한 읽고 및 쓰기를 제한하며, 스크립트가 샌드박스를 위반하면 0이 아닌 종료 코드와 함께 빌드에 실패하게 됨

명시적으로 작성하여 이 문제를 해결하고 선언된 입출력 이외의 파일에 실수로 접근하지 않도록 함.

위와 같은 스크립트의 예시를 보자.

스크립트 A (체크섬 계산): source.txt 파일의 내용을 읽어 checksum.txt 파일을 생성

스크립트 B (HTML 생성): checksum.txt 파일을 읽어 HTML 파일에 내용을 삽입

`FUSE_BUILD_SCRIPT_PHASES`가 켜져있을 때 병렬로 실행하는데, Xcode가 두 종속성 관계를 제대로 추론하지 못함.

스크립트 B가 A보다 먼저 실행되면 checksum.txt 파일이 없어 빌드가 실패하거나, A가 실행 중일 때 B가 오래된 checksum.txt 파일을 읽어 조용히 버그를 만들어낼 수 있습니다.

ENABLE_USER_SCRIPT_SANDBOXING를 YES로 설정한 상태에서는 읽으려는 단계에서 실패하게 되고, 명시적인 실패를 통해 누락된 종속성을 명확하게 찾아낼 수 있음.

Xcode의 Build Settings 혹은 xcconfig를 통해서 설정을 YES로 줄 수 있음.

sandbox shell scripts를 활용하면 올바른 종속성 정보를 통해 증분빌드를 가능하게 하는 올바른 종속성 정보를 가질 수 있음.

왜냐하면, 입출력 파일의 변화가 없다는 확신을 통해 빌드 과정을 건너뛸 수 있기 때문이며, 그렇지 않은 경우에는 Xcode는 스크립트를 다시 실행함.

샌드박싱을 통해 올바르게 정의된 종속성 정보를 통하여 `FUSE_BUILD_SCRIPT_PHASES`와 함께 병렬로 실행할 수도 있음.

Xcode가 Swift Target 간의 종속성을 사용하여 빌드에서 최대 병렬 처리량을 추출하는 방법을 살펴보고 프로젝트 구조 및 구성이 빌드 시간에 미치는 영향도 알아보고자 함.

프로젝트를 구성하는 계층 구조에는 여러 수준이 존재

예를들어 로컬 라이브러리 모음에 의존하는 App Target은 의미론적 경계를 다라 여러 타겟 및 여러 프레임워크로 분할됨.

각 타겟은 다양한 빌드 단계와 절차들을 포함하여 다른 타겟 빌드 단계로 그리고 빌드 단계로부터 파일 의존성을 생성하고 사용함.

프로젝트가 커지면서 작업 그래프의 크기와 복잡성도 커짐

Xcode 빌드 시스템이 이런 계층 구조를 평면화하면서 빌드를 여러 작업들로 분할하고, 이런 작업들은 모든 타겟의 빌드 단계에 해당함.

Swift 타겟에 특화된 한 종류의 작업은 컴파일이고, Swift 타겟의 소스 코드를 바이너리 제품으로 빌드하는 것은 일반적으로 빌드 계획이나

컴파일 및 연결을 위한 많은 하위 작업을 포함하는 복잡한 작업으로 이러한 작업의 Swift Driver라는 Xcode toolchain에 위임.

드라이버는 타겟 소스 코드에 필요한 컴파일러 및 링커 호출을 구성하는 시기와 방법에 대한 정보를 가지고 있음.

Swift 코드를 포함하는 모든 타겟은 배포 단위인 모듈에도 해당됨.

이 타겟의 공개 인터페이스를 캡처하는 바이너리 모듈 파일은 다운스트림 타겟이 컴파일을 시작하는데 필요한 빌드 product임.

Swift Driver는 최적화 기회를 최대화하도록 하는 하나의 컴파일러 작업을 예약.

필요한 컴파일 노력을 병렬로 실행할 수 있는 더 작은 하위 작업으로 나눔.

이 중 일부는 증분 빌드에서 다시 실행할 필요가 없음.

Swift 모듈을 생성하려면 각 컴파일 작업의 부분적인 중간 product를 병합하는 추가 단계가 필요함.

타겟에 있는 소스 파일의 수가 많다면 개별 파일은 일괄 컴파일 하위 작업에 할당될 수 있음.

빌드 로그는 일괄 컴파일 작업에 할당되는 소스 파일을 강조 표시하고 각 파일의 진단에 대해 별도의 항목을 사용

다양한 소스 파일에 걸쳐 타겟의 빌드를 병렬화할 수 있는 것은 더 빠르고 작은 증분빌드에 중요하기 때문에 디버그 빌드가 증분 컴파일 모드 설정을 사용하는지 확인.

Swift의 타겟 의존성은 퍼블릭 인터페이스를 캡처하는 바이너리 모듈 파일을 제공함으로써 해결.

이런 의존성 관계를 해결하면 위와 같은 순서로 이어짐.

각 타겟에 대한 최상위 Swift Driver 작업 및 각 타겟의 개별 하위 작업이 타임라인에 나타남.

Xcode 14 이전의 빌드 시스템은 이원화 된 구조.

Xcode의 빌드 시스템은 전체적인 빌드 단계를 관리했고, Swift 코드 컴파일은 Swift 드라이버라는 별도의 도구에서 독립적으로 관리.

기존에는 두 스케줄러가 각자 시스템 CPU 코어를 최대한 활용하려다 보니 서로 경쟁하며 리소스를 비효율적으로 사용하는 CPU 수를 초과해서 사용하는 문제가 발생

Xcode 14에서는 빌드 시스템과 컴파일러가 완전히 통합되어서 중앙 관리자가 통합 관리함.

중앙 관리자는 사용 가능한 리소스 만큼만 사용하도록 보장.

Xcode14 이후부터 스케줄러 기본 값은 사용 가능한 작업 즉, 종속성이 충족되어서 이동할 준비가 된 작업은 8개의 사용 가능한 실행 슬롯 중 하나에 할당.

코어 수가 많을수록 많은 시스템에서는 더 많은 동시 작업을 수행할 수 있음.

하위 작업 컴파일의 부분적 결과들은 타겟의 최종 모듈 제품에 병합.

제품이 사용 가능하게 되면, 다운스트림 타겟이 컴파일을 시작할 수 있음.

Xcode 14 및 Swift 5.7에서는 새롭게 타겟 모듈의 구성이 모든 프로그램 소스 파일에서 직접 별도의 모듈 emit-module 작업에서 수행.

이는 타겟 종속성이 emit-module 작업이 완료되는 즉시 다른 컴파일러 작업을 기다리지 않고 컴파일을 시작할 수 있음을 의미

빌드 시간을 전체 프로젝트로 확장해서 보면 전반적으로 비슷한 양의 작업을 수행하고 있지만 빌드 시스템은 컴퓨터의 리소스를 더 효율적으로 사용할 수 있음.

따라서 종종 더 빌드를 더 빠르게 마무리할 수 있음.

빌드 시스템이 Swift 빌드 시에 수행할 수 있는 두 번째 Cross-Target 최적화 기능인 즉시 링킹(Eager Linking)이 존재.

링킹 과정에도 유사한 최적화가 적용되는데 다운스트림 타겟의 링커가 업스트림 타겟의 최종 링크 Product를 기다려야 했음.

먼저 생성되는 심볼 목록이 담긴 텍스트 기반 stub 파일에만 의존하면 되므로 링킹을 즉시 시작할 수 있음.

의존성의 대상이 무거운 최종 결과물에서 가벼운 텍스트 파일로 바뀌면서 링킹 작업이 훨씬 앞당겨짐.

이 경우 타겟 B가 타겟 A를 연결하기 때문에 타겟 B의 링크 작업은 타겟 A의 링크된 출력이 생성되고 자체 컴파일 작업이 완료될 때까지 기다려야 함.

즉시 링킹을 사용하면, 타겟 B의 링크 작업이 타겟 A의 emit-module 작업에 의존할 수 있고, 그 결과 타겟 B는 링킹을 빌드 초기에 시작할 수 있음.

타겟 A와 병렬로 실행하며 임계 경로(Critical Path)를 단축할 수 있음.

종속성이 링크된 제품에 의존하는 대신 이전 빌드 프로세스에서 emit-module 작업에 의해 생성된 텍스트 기반 동적 라이브러리 스텁에 의존.

이 스텁에는 링크된 제품에 심볼 목록이 포함되어 있음.

Xcode 빌드 설정을 사용해 이 최적화를 활성화할 수 있음. Xcode 빌드 설정을 사용해 이 최적화를 활성화 할 수 있고

즉시 링킹은 의존성 항목에 의해 동적으로 링킹된 모든 순수 Swift 타겟에 적용

Xcode 14의 빌드 시스템 개선은 단순한 속도 향상이 아니라, 병렬화를 극대화하고, 개발자에게 빌드 과정을 투명하게 보여주며, 리소스를 가장 효율적으로 사용하도록 설계된 근본적인 구조 변화.

이제 우리는 빌드 시간을 막연히 기다리는 대신, 새로운 도구와 지식을 활용해 직접 분석하고 개선할 수 있게 되었고, 이 글에서 소개된 지식을 바탕으로 불필요한 순차 실행 스크립트는 없는지, 타겟 간 의존성이 비효율적으로 구성되지는 않았는지 점검.

(링크)

https://www.youtube.com/watch?v=yo8_luxkSXY&t=4s

swift rethrows

lgvv — Wed, 3 Dec 2025 21:16:28 +0900

swift rethrows

함수나 메서드는 rethrows 키워드를 사용하여 선언할 수 있음.
이는 함수 매개변수 중 하나가 에러를 던질 경우에만 에러를 던진다는 것을 의미.
이러한 함수와 메서드를 rethrowing 함수(rethrowing functions) 또는 rethrowing 메서드(rethrowing methods)라고 부름.

func someFunction(callback: () throws -> Void) throws {
    try callback()
}

rethrowing 함수와 메서드는 적어도 하나의 throwing 함수 매개변수를 가져야 함.
rethrowing 함수나 메서드는 오직 catch 블록 안에서만 throw 문을 포함할 수 있음.

이 규칙을 통해 do-catch 구문 안에서 throwing 함수를 호출하고, catch 블록에서 다른 에러를 던지며 에러를 처리할 수 있음.
또한 catch 블록은 반드시 rethrowing 함수의 throwing 매개변수 중 하나가 던진 에러만 처리해야 함.

예를 들어, 다음 코드는 잘못된 코드입
왜냐하면 catch 블록에서 alwaysThrows()가 던진 에러를 처리하려고 하기 때문

func alwaysThrows() throws {
    throw SomeError.error
}

func someFunction(callback: () throws -> Void) rethrows {
    do {
        try callback()
        try alwaysThrows()  // Invalid, alwaysThrows() isn't a throwing parameter
    } catch {
        throw AnotherError.error
    }
}

throwing 메서드는 rethrowing 메서드를 오버라이드할 수 없음.
throwing 메서드는 rethrowing 메서드에 대한 프로토콜 요구사항을 충족할 수 없음.

반대로, rethrowing 메서드는 throwing 메서드를 오버라이드할 수 있음.
rethrowing 메서드는 throwing 메서드에 대한 프로토콜 요구사항을 충족할 수 있음.

또한, rethrowing 대신 제네릭 코드에서 특정 에러 타입을 throw하는 방법을 사용할 수도 있음.

func someFunction<E: Error>(callback: () throws(E) -> Void) throws(E) {
    try callback()
}

이러한 방식으로 에러를 전달하면 에러 타입에 대한 정보를 그대로 보존할 수 있음.
하지만, rethrows로 함수를 표시하는 것과 달리, 이 방식은 동일한 타입의 에러를 함수가 직접 던지는 것을 막아주지는 않음.

코드 샘플

//
//  RethrowsExample.swift
//  ArchitetureExample
//
//  Created by Geon Woo lee on 12/2/25.
//

import Foundation

fileprivate enum SomeError: Error {
    case error
}

fileprivate enum AnotherError: Error {
    case error
}

fileprivate final class SomeClass {
    func alwaysThrows() throws {
        throw SomeError.error
    }
    
    func someFunction(callback: () throws -> Void) throws {
        try callback()
    }
    
//    func someFunction(callback: () throws -> Void) rethrows {
//        do {
//            try callback()
//            try alwaysThrows()  // Invalid, alwaysThrows() isn't a throwing parameter
//        } catch {
//            throw AnotherError.error
//        }
//    }
    
    func someFunction2(callback: () throws -> Void) rethrows {
        try callback()
    }
    
    func someFunction3(callback: () throws -> Void) throws {
        do {
            try callback()
            try alwaysThrows()
        } catch {
            throw AnotherError.error
        }
    }
    
    func someFunction4(callback: () throws -> Void) throws {
        do {
            try callback()
            try alwaysThrows()
        } catch {
            throw AnotherError.error
        }
    }
    
    func someFunction5<E: Error>(callback: () throws(E) -> Void) throws(E) {
        try callback()
    }
}

import SwiftUI

fileprivate struct PreviewView: View {
    var body: some View {
        Button {
            buttonTapped4()
        } label: {
            Text("Button")
        }
    }
    
    private func buttonTapped() {
        do {
            let someClass = SomeClass()
            try someClass.someFunction(callback: someClass.alwaysThrows)
        } catch {
            print(type(of: error)) // SomeError
        }
    }
    
    private func buttonTapped2() {
        do {
            let someClass = SomeClass()
            try someClass.someFunction2(callback: someClass.alwaysThrows)
        } catch {
            print(type(of: error))
        }
    }
    
    private func buttonTapped3() {
        do {
            let someClass = SomeClass()
            try someClass.someFunction3 { }
        } catch {
            print(type(of: error)) // AnotherError
        }
    }
    
    private func buttonTapped4() {
        do {
            let someClass = SomeClass()
            try someClass.someFunction4 { }
        } catch {
            print(type(of: error)) // AnotherError
        }
    }
    
    private func buttonTapped5() {
        let someClass = SomeClass()
        someClass.someFunction5 { }
    }
}

#Preview {
    PreviewView()
}

(참고)
https://docs.swift.org/swift-book/documentation/the-swift-programming-language/declarations

AVAudioEngine, AVAudioNode 정리

lgvv — Wed, 26 Nov 2025 01:09:49 +0900

AVAudioEngine, AVAudioNode 정리

AVAudioEngine과 관련한 내용을 모아서 정리

AVAudioEngine
- 오디오 렌더링이란?
- Overview
- Create an Engine for Audio File Playback
AVAudioNode
- Overview
- Configuring an Input Format Bus
  - AVAudioNodeBus
  - inputFormat(forBus:)
  - name(forInputBus:)
  - numberOfInputs
- Creating an Output Format Bus
  - outputFormat(forBus:)
  - name(forOutputBus:)
  - numberOfOutputs
- Installing and Removing an Audio Tap
  - installTap(onBus:bufferSize:format:block:)
  - removeTap(onBus:)
  - typealias AVAudioNodeTapBlock
- Getting the Audio Engine for the Node
  - engine
- Getting Audio Node Properties
  - auAudioUnit
  - latency
  - outputPresentationLatency
- Resetting the Audio Node
  - reset()
- Constants
  - typealias AVAudioNodeCompletionHandler

AVAudioEngine

오디오 노드들의 그래프를 관리하고 재생을 제어하며 실시간 렌더링 제약을 구성하는 객체

AVAudioEngine

오디오 렌더링이란?

오디오 데이터를 처리해서 최종적인 PCM 샘플로 만들어내는 작업

여러 Audio Node의 처리 결과를 합치고 이펙트(효과)를 적용하고 믹싱하고 최종적으로 출력할 수 있는 형태로 데이터를 계산해서 생산하는 과정을 의미.

실시간 렌더링과 수동 렌더링이 존재

실시간 렌더링의 경우에는 AudioEngine이 자동으로 주기적으로 콜백을 받아 오디오 샘플을 생성

수동 렌더링의 경우에는 앱이 직접 오디오 엔진에 렌더링을 요청해서 오디오 샘플을 생성해서 다 빠르게 처리할 수 있음.

Overview

오디오 엔진 객체는 AVAudioNode 인스턴스를 포함하며 이를 서로 연결해 오디오 처리 체인을 구성

Overview

런타임 동안 오디오 노드를 연결하거나 연결 해제하고 제거할 수 있지만 몇 가지 제한이 존재.

채널 수가 서로 다르거나 믹서(mixer)인 오디오 노드를 제거하면 그래프가 깨질 수 있으며, 믹서의 상위(upstream)에 있는 노드만 재연결해야 함.

기본적으로 Audio Engine은 연결된 오디오 기기로 실시간 렌더링을 수행.

실시간 또는 실시간보다 더 빠르게 렌더링해야 하는 경우, 엔진을 수동 렌더링 모드(manual rendering mode)로 설정할 수 있음.

이 모드에서 엔진은 오디오 기기와의 연결을 끊고 앱이 직접 렌더링을 제어함.

Create an Engine for Audio File Playback

오디오 파일 재생을 위한 순서

1. 오디오 파일을 재생하기 위해서는 우선 읽기 모드로 열 수 있는 파일을 기반으로 AVAudioFile 객체를 생성
2. 오디오 엔진(AVAudioEngine) 객체와 AVAudioPlayerNode 인스턴스를 만들고 플레이어 노드를 엔진에 attach
3. 플레이어 노드를 오디오 엔진의 output node에 연결(connect)
4. 오디오 엔진은 오디오 출력을 담당하는 output node를 통해 사운드를 재생
- 4-1. output node는 엔진에서 처음 접근할 때 자동으로 생성되는 싱글턴(singleton)
5. 오디오 파일 전체를 재생하도록 스케줄하고, 재생이 완료되면 콜백을 통해 앱에 알려줌.
6. 오디오를 재생하기 전에 AudioEngine을 시작
7. 재생이 완료되면 오디오 플레이어 노드랑 오디오 엔진을 정지.

샘플코드

func execute() throws {
    let audioFile = try AVAudioFile(forReading: URL(string: "")!)
    let audioEngine = AVAudioEngine()
    let playerNode = AVAudioPlayerNode()
    
    // AVAudioEngine 객체와 AVAudioPlayerNode 인스턴스를 만들고 플레이어 노드를 엔진에 attach
    audioEngine.attach(playerNode)
    
    
    // 플레이어 노드를 출력 노드에 연결
    audioEngine.connect(
        playerNode,
        to: audioEngine.outputNode,
        format: audioFile.processingFormat
    )
    
    // 오디오 파일 전체를 재생하도록 스케줄하고, 재생이 완료되면 콜백을 통해 앱에 알려줌.
    playerNode.scheduleFile(
        audioFile,
        at: nil,
        completionCallbackType: .dataPlayedBack
    ) { _ in
        /* Handle any work that's necessary after playback. */
    }
    
    // 오디오를 재생하기 전에 AudioEngine을 시작
    try audioEngine.start()
    playerNode.play()
    
    // 재생이 완료되면 오디오 플레이어 노드랑 오디오 엔진을 정지.
    playerNode.stop()
    audioEngine.stop()
}

AVAudioNode

오디오 생성, 처리 또는 입출력(I/O) 블록에 사용하는 객체

iOS 8.0+
iPadOS 8.0+
Mac Catalyst 13.1+
macOS 10.10+
tvOS 9.0+
visionOS 1.0+
watchOS 2.0+

Overview

AVAudioEngine 객체는 오디오 노드 인스턴스를 포함하며, 이 기본 클래스는 공통 기능을 제공

AVAudioEngine 객체의 인스턴스는 엔진에 연결되지 않으면 실질적인 기능을 수행하지 않음.

노드는 입력(input)과 출력(output) 버스(bus)를 가지며, 이 버스들이 연결 지점 역할을 함.

이펙트(effect) 노드는 하나의 입력 버스와 하나의 출력 버스를 가짐

믹서(mixer) 노드는 여러 입력 버스와 하나의 출력 버스를 가짐

각 버스는 프레임워크가 샘플 레이트(sample rate)와 채널 수(channel count)로 표현하는 포맷(format)을 포함

노드 간 연결 시 포맷은 정확히 일치해야 하고 AVAudioMixerNode와 AVAudioOutputNode는 예외

Configuring an Input Format Bus

AVAudioNodeBus

AVAudioNode의 버스 인덱스
AVAudioNode 객체는 여러 개의 입력 및 출력 버스를 가질 수 있음.
AVAudioNodeBus는 버스를 0부터 시작하는 인덱스로 표현.

public typealias AVAudioNodeBus = Int

inputFormat(forBus:)

지정한 bus의 입력 포맷을 가져옴
해당 버스의 입력 포맷을 나타내는 AVAudioFormat 인스턴스를 반환

func inputFormat(forBus bus: AVAudioNodeBus) -> AVAudioFormat

name(forInputBus:)

지정한 입력 버스의 이름을 가져옴
오디오 노드의 입력 버스
인풋 버스의 이름

func name(forInputBus bus: AVAudioNodeBus) -> String?

numberOfInputs

인풋 버스의 수

var numberOfInputs: Int { get }

Creating an Output Format Bus

outputFormat(forBus:)

지정한 버스의 출력 포맷

func outputFormat(forBus bus: AVAudioNodeBus) -> AVAudioFormat

name(forOutputBus:)

지정한 출력 버스의 이름을 가져옴

func name(forOutputBus bus: AVAudioNodeBus) -> String?

numberOfOutputs

노드의 출력 버스 수

var numberOfOutputs: Int { get }

Installing and Removing an Audio Tap

installTap(onBus:bufferSize:format:block:)

지정한 버스에 오디오 탭(audio tap)을 설치해 노드의 출력을 녹음, 모니터링, 관찰 할 수 있음.
엔진이 실행 중일 때도 탭을 설치하거나 제거할 수 있음.
하나의 버스에는 한 개의 탭만 설치할 수 있음.
bus
- 탭을 연결한 출력 버스
bufferSize
- 들어오는 오디오 버퍼의 크기 (실제 구현에서는 다른 크기 선택 가능)
format
- nil이 아닌 경우에 지정한 출력 버스에 해당 포맷 지정
- 이미 연결된 상태의 출력 버스에 탭을 연결하면 오류가 발생
- 탭과 연결 포맷 둘 다 nil이 아닌 경우에 두 포맷을 동일해야 하며, 그렇지 않은 경우에는 나중에 적용된 포맷이 이전 포맷을 덮어씀.
- AVAudioOutputNode의 경우 탭 포맷은 반드시 nil로 지정해야 함.
tapBlock
- 오디오 버퍼를 처리하기 위해 프레임워크가 호출하는 블록
- 프레임워크는 tapBlock을 메인 스레드가 아닌 다른 스레드에서 호출할 수 있음.

func installTap(
    onBus bus: AVAudioNodeBus,
    bufferSize: AVAudioFrameCount,
    format: AVAudioFormat?,
    block tapBlock: @escaping AVAudioNodeTapBlock
)

removeTap(onBus:)

지정한 버스의 오디오 탭을 제거

func removeTap(onBus bus: AVAudioNodeBus)

AVAudioNodeTapBlock

오디오 노드의 출력을 복사하여 받는 블록(block)
프레임워크는 tapBlock을 메인 스레드가 아닌 다른 스레드에서 호출할 수 있음.
buffer
- 시스템이 오디오 노드의 출력에서 캡처한 오디오 버퍼
when
- 시스템이 해당 버퍼를 캡처한 시점

typealias AVAudioNodeTapBlock = (AVAudioPCMBuffer, AVAudioTime) -> Void

Getting the Audio Engine for the Node

engine

해당 노드를 관리하는 Audio Engine 존재하는 경우

var engine: AVAudioEngine?

Getting the Latest Node Render Time

lastRenderTime

가장 최근의 렌더링 시간
엔진이 실행 중이 아니거나 노드를 입력(input) 혹은 출력(output) 노드에 연결하지 않은 경우 이 값은 nil

var lastRenderTime: AVAudioTime? { get }

Getting Audio Node Properties

auAudioUnit

Audio Unit 객체로 구현체의 오디오 유닛을 래핑하거나 기반
앱이 오디오 유닛을 패키징하는 방식에 따라 구현체의 오디오 유닛을 래핑(wrap)하거나 기반(underlie)으로 하는 AUAudioUnit을 제공
- 엔진 상태와 충돌할 수 있는 작업(초기화 상태 변경, 스트림 포맷 변경, 채널 레이아웃 변경, 다른 오디오 유닛과의 연결 변경 등)은 직접 수행하지 말것
앱은 이를 통해 커스텀 속성을 제어하고, 프리셋을 선택하며, 파라미터를 변경할 수 있음.

var auAudioUnit: AUAudioUnit { get }

latency

노드의 processing latency 시간
이 latency는 신호 처리로 인한 딜레이를 나타내어 값이 0인 경우에 latency가 없거나 알 수 없는 경우

var latency: TimeInterval { get }

outputPresentationLatency

노드 이후(render downstream)의 최대 렌더 파이프라인 지연 시간
이 지연은 노드의 출력에서 오디오가 실제로 재생되기까지 걸리는 최대 시간을 나타냄

var outputPresentationLatency: TimeInterval { get }

Resetting the Audio Node

reset()
- 오디오 유닛의 이전 처리 상태를 초기화

Constants

AVAudioNodeCompletionHandler
- 오디오 노드에서 사용하는 일반적인 콜백 핸들러

AVAudioNode에는 이와 별개로 다른 노드들도 존재

(참고)

https://developer.apple.com/documentation/avfaudio/avaudionode

AVAudioFormat 정리

lgvv — Mon, 24 Nov 2025 23:58:17 +0900

AVAudioFormat 정리

AVAudioFormat에 대해서 정리하며 연관된 지식도 모두 함께 정리.

AVAudioFormat
AVAudioFormat의 프로퍼티들
- Getting the Audio Stream Description
  - streamDescription
- Getting Audio Format Values
  - sampleRate
  - channelCount
  - channelLayout
  - formatDescription
- Determining the Audio Format
  - isInterleaved
  - isStandard
  - commonFormat
  - settings
  - magicCookie
AVAudioFormat과 AudioStreamBasicDescription의 비교 정리
Channel과 ChannelLayout의 차이
AVAudioCommonFormat 정리

AVAudioFormat

오디오 포맷의 표현을 설명하는 객체

샘플 레이트, 채널 수 등을 포함하는 속성들을 포함하여 오디오 데이터가 어떤 구조로 구성되어 있는지를 알려주는 객체.

iOS 8.0+
iPadOS 8.0+
Mac Catalyst 13.1+
macOS 10.10+
tvOS 9.0+
visionOS 1.0+
watchOS 2.0+

Overview

AVAudioFormat 클래스는 Core Audio의 AudioStreamBasicDescription을 감싸는 래퍼.

Core Audio에서 표준으로 사용하는 디인터리브(Deinterleaved)된 32비트 부동소수점(Float32) 포맷을 포함

일반적인 오디오 포맷을 손쉽게 다룰 수 있도록 여러 초기화 메서드와 접근자를 제공

해당 클래스의 인스턴스 프로퍼티를 초기화 후에는 변경할 수 없음 (Immutable)

AVAudioFormat의 프로퍼티들

streamDescription

오디오 데이터 스트림의 오디오 포맷 속성
하위 레벨 오디오 API에서 사용할 수 있는 AudioStreamBasicDescription을 반환

var streamDescription: UnsafePointer<AudioStreamBasicDescription> { get }

sampleRate

오디오 포맷의 샘플링 레이트(Hz 단위)

var sampleRate: Double { get }

channelCount

오디오 데이터의 채널 수
- AVAudioChannelCount는 UInt32로 이보다 큰 경우 런타임 에러가 발생할 수 있음.

var channelCount: AVAudioChannelCount { get }

channelLayout

기본 오디오 채널 레이아웃
2채널을 초과하는 포맷에서만 채널 레이아웃이 필요

var channelLayout: AVAudioChannelLayout? { get }

formatDescription

Core Media API와 함께 사용할 오디오 포맷

var formatDescription: CMAudioFormatDescription { get }

isInterleaved

샘플이 하나의 스트림으로 믹스되는지 여부를 나타내는 불리언 값.
이 값은 PCM 포맷에서만 유효.

var isInterleaved: Bool { get }

isStandard

포맷이 디인터리브드(deinterleaved)된 네이티브 엔디안(float) 상태인지 여부를 나타내는 불리언 값
- 이 값은 포맷이 AVAudioCommonFormat.pcmFormatFloat32일 경우 true를 반환
- 그 외의 경우는 false를 반환

var isStandard: Bool { get }

commonFormat

AVAudioCommonFormat 식별자 인스턴스

var commonFormat: AVAudioCommonFormat { get }

settings

이 설정에 들어가는 딕셔너리는 AudioStreamBasicDescription이 표현하는 모든 형식을 지원하지 않음.
따라서 해당 포맷을 지원하지 않는 경우 이 속성은 nil을 반환

var settings: [String : Any] { get }

magicCookie

인코더와 디코더가 필요로 하는 메타데이터를 포함한 객체.
인코더는 magicCookie 객체를 생성하며 일부 디코더는 이를 통해 올바르게 디코딩을 수행할 수 있음.
- 참고로 magicCookie는 AAC, ALAC 같은 일부 코덱은 압축 형식에 대한 추가 정보가 있어야 제대로 디코딩 할 수 있음.
- 인코더는 이 정보를 생성해서 디코더에 전달해야 함.

var magicCookie: Data? { get set }

AVAudioFormat과 AudioStreamBasicDescription의 비교 정리

AVAudioFormat

AVFAduio 프레임워크에 속하며 오디오 엔진(API: AVAudioEngine, AVAudioPlayerNode 등)
Swift 환경에서 오디오 포맷을 다룰 때
안전한 오디오 처리 로직을 구성할 때

목적: 오디오 포맷을 쉽게 다룰 수 있게 하는 추상화된 인터페이스

AudioStreamBasicDescription(ASBD)

Core Audio 프레임워크에 속하는 저수준 API을 위해서 사용
직접 버퍼 관리, PCM 데이터 처리
압축 및 비압축 오디오의 실제 패킷 구조를 다뤄야 하는 상황

목적: 하드웨어 수준에서 오디오 데이터를 정확히 기술하기 위한 로우 레벨 데이터 구조

Channel과 ChannelLayout의 차이

채널(Channel): 오디오 트랙 하나를 의미

채널 레이아웃(Channel Layout): 채널이 물리적으로 어디에 배치되는지 나타냄
5.1채널 이상이면 각 채널의 위치 정보가 필요합니다.

채널(Channel): 오디오 트랙 하나를 의미

예: 모노 → 1채널
스테레오 → 2채널 (왼쪽, 오른쪽)
서라운드 5.1 → 6채널 (앞왼, 앞오, 중앙, 서브우퍼, 뒤왼, 뒤오)
- 경우에 따라 다르지만 우퍼는 저음으로 방향이 존재하지 않아서 .1을 붙임.

채널 레이아웃(Channel Layout): 채널이 물리적으로 어디에 배치되는지 나타냄

단순히 “채널 수 = 6”이라고 해도, 어떤 채널이 앞, 뒤, 좌, 우인지를 정의하지 않으면 스피커 배치가 올바르지 않을 수 있음
- 그래서 2채널 이상일 때만 필요
- 2채널 스테레오는 일반적으로 왼쪽과 오른쪽이 명확하기 때문에 레이아웃이 필수가 아니지만, 5.1채널 이상이면 각 채널의 위치 정보가 필요

AVAudioCommonFormat 정리

일반적인 오디오 포맷을 설명하는 포맷 옵션으로 Enum으로 설정.

otherFormat
- AVAudioCommonFormat에서 정의하고 있는 것 외에 다른 형식
pcmFormatFloat32
- 표준 형식을 네이티브 엔디언의 부동소수점(float) 형태로 표현한 형식
pcmFormatFloat64
- 네이티브 엔디언(double) 형식으로 표현한 포맷
pcmFormatInt16
- 서명된 16비트 네이티브 엔디언 정수(signed 16-bit native-endian integer)로 표현한 포맷
pcmFormatInt32
- 서명된 32비트 네이티브 엔디언 정수(signed 32-bit native-endian integer)로 표현한 포맷

AudioStreamBasicDescription 정리

lgvv — Mon, 24 Nov 2025 23:40:30 +0900

AudioStreamBasicDescription 정리

CoreAudioType에 속하는 AudioStreamBasicDescription를 정리.

AudioStreamBasicDescription
패킷의 지속 시간(Duration) 계산
구조체의 모든 필드를 0으로 초기화하는 코드
Core Audio에서 사용하는 용어 정의
AudioStreamBasicDescription의 Instance Property
- mFormatIDmSampleRatemBitsPerChannel
- mBytesPerPacket
- mReserved
- mFramesPerPacket
- mChannelsPerFrame
- mBytesPerFrame
- mFormatFlags

AudioStreamBasicDescription

오디오 스트림을 위한 포맷 명세서.

오디오 데이터가 어떤 형식으로 구성되어 있는지를 정의하는 명세서

오디오 스트림의 구조를 기술하는 메타데이터의 성격

iOS 2.0+
iPadOS 2.0+
macOS 10.0+
tvOS 9.0+
visionOS 1.0+
watchOS 3.0+

Overview

오디오 스트림 기본 설명(Audio Stream Basic Description, ASBD)을 구성할 때 선형 PCM(Linear PCM) 포맷 또는 채널 크기가 동일한 CBR(Constant Bit Rate) 포맷을 지정할 수 있음.

만약 가변 비트레이트(VBR) 오디오거나 혹은 채널 크기가 서로 다른 CBR 오디오
각 패킷의 정보를 추가로 기술하기 위해 AudioStreamPacketDescription 구조체도 함께 사용해야 함.

만약 필드 값이 0이면, 해당 값이 알 수 없거나 혹은 format에 적용되지 않음을 의미

또한, 새로운 ASBD 구조체를 생성할 때는 모든 필드를 명시적으로 0으로 초기화하는 것을 권장

구조체의 모든 필드를 0으로 초기화하는 코드

공식 문서에는 C 언어로 작성되어 있으나 Swift 문법 예제 추가

// MARK: - C Language
AudioStreamBasicDescription myAudioDataFormat = {0};

// MARK: - Swift Language

var myAudioDataFormat = AudioStreamBasicDescription()
myAudioDataFormat.mSampleRate = 0
myAudioDataFormat.mFormatID = 0
myAudioDataFormat.mFormatFlags = 0
myAudioDataFormat.mBytesPerPacket = 0
myAudioDataFormat.mFramesPerPacket = 0
myAudioDataFormat.mBytesPerFrame = 0
myAudioDataFormat.mChannelsPerFrame = 0
myAudioDataFormat.mBitsPerChannel = 0
myAudioDataFormat.mReserved = 0

패킷의 지속 시간(Duration) 계산

오디오 스트림에서 하나의 패킷이 재생되는 시간을 계산하려면 AudioStreamBasicDescription에 존재하는 2개의 필드를 활용

mSampleRate: 초당 샘플 수
mFramesPerPacket: 패킷 당 프레임 수

// MARK: - C Language
duration = (1 / mSampleRate) * mFramesPerPacket

// MARK: - Swift Language
let duration = (1.0 / sampleRate) * Double(framesPerPacket)

수식에 대한 설명

x = 1 / mSampleRate: 한 샘플의 재생 시간
y = mFramesPerPacket: 패킷 내 프레임의 수

즉, x와 y를 곱하면 해당 패킷이 재생되는 총 시간을 구할 수 있음.

샘플코드

let sampleRate: Double = 44100  // 1초에 44100 샘플
let framesPerPacket: UInt32 = 1024

let duration = (1.0 / sampleRate) * Double(framesPerPacket)
print("패킷 지속 시간: \(duration) 초")

Core Audio에서 사용하는 용어 정의

Core Audio에서 용어를 아래와 같은 의미로 정의하여서 사용

오디오 스트림(Audio Stream)
- 소리를 표현하는 연속적인 데이터 시퀀스를 의미
- 에시) 노래 한 곡의 데이터가 오디오 스트림
채널(Channel)
- 모노 오디오의 독립적인 트랙을 의미
  - 모노 스트림 : 1개 채널
  - 스테레오 스트림 : 2개 채널
샘플(Sample)
- 오디오 스트림 내 단일 채널의 단일 수치 값을 의미.
프레임(Frame)
- 시간적으로 일치하는 샘플들의 집합
- 예시) Linear PCM 스테레오 오디오 파일은 프레임당 2개의 샘플을 가짐
- 왼쪽 채널 1샘플 + 오른쪽 채널 1샘플 = 1 프레임
패킷(Packet)
- 연속된 1개 이상의 프레임 집합을 의미
- 패킷은 특정 오디오 데이터 포맷에서 시간을 측정할 수 있는 가장 작은 단위
- Linear PCM에서는 패킷이 1 프레임을 담음.
- 압축 포맷에서는 일반적으로 여러 프레임 담음.
- 일부 포맷에서는 패킷당 프레임 수가 가변적일 수 있음.
샘플 레이트(Sample Rate)
- 비압축 오디오: 초당 프레임 수(frames per second)
- 압축 오디오: 압축을 해제했을 때의 동등한 초당 프레임 수

AudioStreamBasicDescription의 Instance Property

해당 객체에 존재하는 인스턴스 프로퍼티 정리

mFormatID

스트림의 일반 오디오 데이터 형식을 지정하는 식별자
지원되는 오디오 형식을 나타내는 식별자
- 간단하게 코덱에 대한 정보

var mFormatID: AudioFormatID

mFormatFlags

형식별 세부 정보를 지정하기 위한 포맷 전용 플래그
플래그가 없음을 나타내려면 0으로 설정

var mFormatFlags: AudioFormatFlags

mSampleRate

압축 포맷의 경우 압축을 해제한 데이터 기준 초당 프레임 수를 나타냄
mSampleRate 필드는 0이 될 수 없음.
- 단, AudioStreamBasicDescription 구조체에서 지원되는 포맷 리스트를 나열할 때는 예외 (kAudioStreamAnyRate로 표현)
- kAudioStreamAnyRate은 오디오 스트림이 어떤 샘플 레이트라도 사용할 수 있음을 나타내는 값

var mFormatFlags: AudioFormatFlags

단, AudioStreamBasicDescription 구조체에서 지원되는 포맷 리스트를 나열할 때는 예외라는 의미는

녹음할 때, 샘플 레이트, 채널 수 등을 정확하게 넣어주어야 하나, OS나 라이브러리가 단순히 어떤 포맷들을 지원하는지 목록으로 나열해줄 때는 샘플레이트가 정확히 무엇인지는 중요하지 않기 때문에 mSampleRate = kAudioStreamAnyRate와 같은 특수값으로 표현.

mBitsPerChannel

오디오 샘플 하나를 표현하는 비트 수
압축 포맷의 경우에는 패킷 내 샘플 비트 수를 정확하게 알 수 없어서 mBitsPerChannel 값을 0으로 설정
즉, 비압축 오디오에서는 샘플당 비트 수를 직접 계산하고, 압축 오디오에서는 의미 없는 값이므로 0으로 초기화

var mBitsPerChannel: UInt32

linear PCM에서 kAudioFormatFlagsCanonical를 사용하는 경우 비트수를 계산하는 방법

// MARK: - C Language
mBitsPerChannel = 8 * sizeof(AudioSampleType);

// MARK: - Swift Language
let mBitsPerChannel = 8 * MemoryLayout<AudioSampleType>.size // warning: 'AudioSampleType' is deprecated: The concept of canonical formats is deprecated

Xcode 26에서는 아래와 같은 경고가 발생.

warning: 'AudioSampleType' is deprecated: The concept of canonical formats is deprecated

Core Audio 프레임워크에서 AudioSampleType 타입이 더 이상 권장되지 않으며, 예전 “canonical format” 개념 자체가 deprecated 되었음을 의미.

모든 오디오 샘플은 명시적으로 포맷을 지정해야 하고 오래된 기본형 AudioSampleType을 사용하지 말라고 경고를 띄워줌.

아래 샘플 코드처럼 Core Audio에서 AudioSampleType에 의존하기 보단, ASBD 등 명시적으로 포맷을 전환하는 것이 안전.

var asbd = AudioStreamBasicDescription()
asbd.mSampleRate = 44100
asbd.mFormatID = kAudioFormatLinearPCM
asbd.mFormatFlags = kAudioFormatFlagIsFloat | kAudioFormatFlagIsPacked
asbd.mBitsPerChannel = 32
asbd.mChannelsPerFrame = 2
asbd.mBytesPerFrame = asbd.mChannelsPerFrame * (asbd.mBitsPerChannel / 8)
asbd.mFramesPerPacket = 1
asbd.mBytesPerPacket = asbd.mBytesPerFrame * asbd.mFramesPerPacket

mBytesPerFrame

오디오 버퍼에서 한 프레임의 시작 지점부터 다음 프레임 시작 지점까지의 바이트 수
압축 포맷의 경우 이 필드는 0으로 설정

var mBytesPerFrame: UInt32

n개의 채널을 가지는 인터리브드(interleaved) 데이터의 오디오 버퍼에서, 각 샘플이 AudioSampleType일 경우

// MARK: - C Language
mBytesPerFrame = n * sizeof(AudioSampleType)

// MARK: - Swift Language

// 인터리브드 데이터 (n개의 채널)
let nChannels = n // 채널 수
let bytesPerFrame = nChannels * MemoryLayout<AudioSampleType>.size

비인터리브드(noninterleaved, 모노포닉) 데이터의 오디오 버퍼에서, 각 샘플이 AudioSampleType일 경우

// MARK: - C Language
mBytesPerFrame = sizeof(AudioSampleType)

// MARK: - Swift Language

// 비인터리브드 데이터 (모노포닉)
let monoBytesPerFrame = MemoryLayout<AudioSampleType>.size

mChannelsPerFrame

각 오디오 프레임에 포함된 채널 수
이 값은 0이 될 수 없음
- 오디오에서 채널이 0개라는 것은 의미가 없음.
- 0채널이면 소리가 없는 것과 같아서, 프레임 단위 계산이나 버퍼 처리도 불가능
- 따라서 Core Audio에서는 항상 1 이상이어야 함.
  - 1 → 모노
  - 2 → 스테레오
  - 5, 6, 7, 8 → 서라운드 채널 등

var mChannelsPerFrame: UInt32

mBytesPerPacket

오디오 데이터 패킷의 바이트 수
가변 패킷 크기(variable packet size)를 나타내려면 이 필드를 0으로 설정
가변 패킷 크기를 사용하는 포맷의 경우, 각 패킷의 크기는 AudioStreamPacketDescription 구조체를 사용하여 지정

AudioStreamPacketDescription

패킷 크기가 일정하지 않거나 패킷 사이에 불필요한 데이터가 있는 버퍼의 패킷 구조를 위한 구조체
mStartOffset
- 버퍼의 시작 지점부터 해당 패킷의 시작 지점까지의 바이트 수입니다.
mVariableFramesInPacket
- 패킷 내 데이터의 샘플 프레임 수
- 만약 패킷당 프레임 수가 일정한 포맷에서는 이 필드를 0으로 설정
mDataByteSize
- 패킷의 바이트 수

var mBytesPerPacket: UInt32

mFramesPerPacket

오디오 데이터 패킷에 포함된 프레임 수
비압축 오디오의 경우 이 값은 1
가변 비트레이트(VBR) 형식에서는 이 값이 1024(AAC)처럼 더 큰 고정된 숫자.
Ogg Vorbis처럼 패킷마다 프레임 수가 달라지는 형식이라면, 이 필드를 0으로 설정.

var mFramesPerPacket: UInt32

mReserved

구조체를 8바이트 단위로 정렬하기 위해 추가하는 패딩 바이트 수
이 값은 0으로 설정

var mReserved: UInt32

(참고)
https://developer.apple.com/documentation/CoreAudioTypes/AudioStreamBasicDescription

AudioStreamBasicDescription | Apple Developer Documentation

A format specification for an audio stream.

developer.apple.com

AVAudioPCMBuffer 정리

lgvv — Mon, 24 Nov 2025 00:32:15 +0900

AVAudioPCMBuffer 정리

AVAudioPCMBuffer를 학습하고 이와 관련한 개념들을 정리.

AVAudioPCMBuffer 선수 지식 정리
AVAudioPCMBuffer
AVAudioPCMBuffer의 인스턴스 프로퍼티
- AVAudioPCMBuffer().frameLength
- AVAudioPCMBuffer().frameCapacity
- AVAudioPCMBuffer().stride
- AVAudioPCMBuffer().floatChannelData
- AVAudioPCMBuffer().int16ChannelData, AVAudioPCMBuffer().int32ChannelData

AVAudioPCMBuffer 선수 지식 정리

AVAudioPCMBuffer를 학습하기 전에 사전 개념으로 필요.

자세한 이론은 하단의 링크 참고.

PCM(Audio)란?
- Pulse Code Modulation로 디지털 오디오의 가장 기본적인 형태를 의미.
- 아날로그 소리를 일정한 간격으로 샘플링하고, 각 샘플을 디지털(숫자 값)으로 변환한 것.
- 즉, PCM 오디오는 실제 소리의 진폭을 숫자로 표현한 샘플들의 배열

PCM buffer란?
- PCM buffer는 PCM 오디오 샘플을 담고 있는 메모리 공간(버퍼)를 의미.
- 즉, 오디오 데이터 배열을 담은 객체로 transcription, analyze, 재생 등 오디오 처리를 위해 사용
- iOS에서는 AnalyzerInput이나 AVAudioPCMBuffer 같은 객체가 PCM Buffer를 제공.

분석, 전사, 신호 처리 등 연속된 샘플 데이터가 필요한데, PCM buffer는 이 샘플 데이터를 일정한 포맷으로 모아둔 컨테이너 역할.

샘플링 레이트(예: 16kHZ, 44.1kHz), 채널 수(에: 모노, 스트레오), 각 샘플의 비트 깊이(예: 16-bit, 24, bit) 등의 정보와 함께 PCM buffer를 분석 모듈에 제공하면 음성을 텍스트로 변환하거나 VAD(음성 감지) 등을 처리할 수 있음.

AVAudioPCMBuffer

PCM 오디오 포맷과 함께 사용하는 오디오 버퍼를 나타내는 객체

iOS 8.0+
iPadOS 8.0+
Mac Catalyst 13.1+
macOS 10.10+
tvOS 9.0+
visionOS 1.0+
watchOS 2.0+

AVAudioPCMBuffer().frameLength

버퍼의 현재 유효 샘플 프레임 수

var frameLength: AVAudioFrameCount { get set }

기본적으로 버퍼를 생성할 때 frameLength 속성은 유용한 값을 가지지 않으므로, 버퍼를 사용하기 전에 반드시 이 값을 설정.
frameLength 값은 버퍼의 frameCapacity보다 작거나 같아야 함.
deinterleaved 포맷에서는 frameCapacity가 각 채널의 오디오 샘플 수를 의미.
버퍼 내용 수정 작업 중에 frameLength를 변경할 수 있음.
frameLength를 수정하면 내부 AudioBufferList 구조체의 각 AudioBuffer 속성에 있는 mDataByteSize 값도 자동으로 업데이트되며 그 반대도 마찬가지.

정리하자면, frameLength는 버퍼 안에서 실제로 사용 가능한 오디오 샘플의 길이를 나타내는 값.

버퍼를 분석, 재생, 전사 등에 사용하기 전에 정확하게 설정해 주어야 함.

AVAudioPCMBuffer().frameCapacity

버퍼가 담을 수 있는 오디오 샘플 프레임의 최대 용량

var frameCapacity: AVAudioFrameCount { get }

AVAudioPCMBuffer().stride

버퍼의 인터리브된 채널 수

var stride: Int { get }

AVAudioPCMBuffer().floatChannelData

버퍼의 오디오 샘플을 부동소수점(floating point) 값으로 나타낸 것.

var floatChannelData: UnsafePointer<UnsafeMutablePointer<Float>>? { get }

floatChannelData 속성

버퍼의 포맷이 32비트 부동소수점(float)일 경우 버퍼의 오디오 샘플을 가리키는 포인터를 반환
버퍼가 다른 포맷이라면 nil을 반환합니다.

반환되는 포인터 구조

반환되는 포인터는 format.channelCount 개수만큼의 float 포인터 배열
각 포인터는 frameLength만큼의 유효 샘플을 가리키며, 클래스는 샘플 간 stride 값에 따라 메모리를 배치.

포맷별 동작 차이

비인터리브(non-interleaved) 포맷
- 표준 deinterleaved float 포맷처럼 각 채널은 별도의 메모리 영역을 가리킴.
- 이 경우 stride 값은 항상 1
인터리브(interleaved) 포맷
- 샘플이 채널별로 섞여(interleaved) 저장
- 각 포인터는 동일한 버퍼를 가리키지만, 1프레임씩 오프셋(offset) 되어 있음.
- 이 경우 stride 값은 인터리브된 채널 수를 나타냄.

interleaved과 non-interleaved에 대한 정리는 별도로 진행.

AVAudioPCMBuffer().int16ChannelData, AVAudioPCMBuffer().int32ChannelData

int16ChannelData

버퍼의 16비트 정수 오디오 샘플
int16ChannelData 속성은 버퍼의 형식이 2바이트 정수 샘플인 경우 해당 오디오 샘플을 반환하며, 다른 형식의 경우에는 nil 반환

int32ChannelData

버퍼의 32비트 정수 오디오 샘플
int16ChannelData 속성은 버퍼의 형식이 4바이트 정수 샘플인 경우 해당 오디오 샘플을 반환하며, 다른 형식의 경우에는 nil 반환

(링크)

https://developer.apple.com/documentation/AVFAudio/AVAudioPCMBuffer

AVAudioPCMBuffer | Apple Developer Documentation

An object that represents an audio buffer you use with PCM audio formats.

developer.apple.com

https://m.blog.naver.com/vasurada0/220987206351

누워서 읽는 디지털 오디오 포맷 1) PCM (오디오 CD)

아날로그 세계를 디지털로 기록하는 방법우리가 귀로 듣는 소리는 기본적으로 공기를 타고 전파되는 아날로...

blog.naver.com

AssetInventory 정리 + AssetInstallationRequest

lgvv — Sat, 22 Nov 2025 20:03:18 +0900

AssetInventory 정리 + AssetInstallationRequest

AssetInvenotry에 대해서 정리하고 관련된 메서드들 하나씩 정리

AssetInventory
- Overview
- Install Assets
- Manage Assets
Downloading and installing assets
- assetInstallationRequest(supporting:)
Checking asset status
- AssetInventory.Status
  - downloading
  - installed
  - supported
  - unsupported
Type Properties
- AssetInventory.maximumReservedLocales
- AssetInventory.reservedLocales
Type Methods
- AssetInventory.release(reservedLocale: Locale) async -> Bool
- AssetInventory.reserve(locale:)
AssetInstallationRequest
- Overview
- AssetInstallationRequest의 downloadAndInstall()

iOS 26.0+
iPadOS 26.0+
Mac Catalyst 26.0+
macOS 26.0+
visionOS 26.0+

transcription(받아쓰기) 또는 여러 기타 분석에 필요한 Asset 들을 관리함.

class로 구현되어 있음.

Overview

SpeechAnalyzer 클래스를 사용하기 전에, 사용할 모듈에 필요한 에셋을 설치.

이 에셋들은 Apple 서버에서 다운로드되며 시스템이 관리하는 ML 모델.

한 번 에셋을 다운로드 혹은 설치하거나 사용하면 시스템은 이를 자동으로 보관하고 업데이트하여 다른 앱과도 공유.

또한 시스템은 저장 공간과 네트워크 사용량을 제한하기 위해, 앱이 사용할 수 있는 Locale 기반 asset reservations 수를 제한적으로 제공.

앱은 에셋을 직접 다루지 않음. 대신 앱은 모듈 객체를 구성하고, 시스템은 그 구성 내용을 바탕으로 어떤 에셋이 필요한지 판단.

asset reservations이란?

Speech 프레임워크가 사용하는 모델(음성 인식 및 언어 모델 등)은 기기에 다운로드되어 저장.
모든 앱이 무제한으로 모델을 설치하도록 허용할 시 기기 저장 공간이 과도하게 사용되고, 네트워크 트래픽이 많아질 수 있기에 iOS 앱 별로 설치 가능한 모델 개수에 제한.
즉, 하나의 앱이 동시에 보유할 수 있는 언어 모델의 수를 제한.

AssetInventory를 통해 설치 가능 여부를 확인하고, 필요 없는 언어 모델은 사용 중지하여 공간을 확보.

Install assets (에셋 설치하기)

에셋을 설치하는 과정은 다음과 같은 4단계로 이루어짐.

사용하려는 구성(configuration)으로 analyze 모듈 생성.
1. 시스템은 객체 자체가 아니라, 모듈의 구성 정보를 기반으로 필요한 에셋을 설치.
2. 모듈 객체 자체는 이후에 폐기(discard)해도 괜찮음.
앱의 에셋 예약(asset reservations)을 해당 로케일(locale)에 할당
1. Locale 기반 에셋이 필요한 모듈(즉, LocaleDependentSpeechModule 프로토콜을 준수하는 모듈)에만 필요.
2. 그 외 모듈은 이 단계를 건너뛰어도 상관 없음.
3. 클래스가 필요 시 자동으로 수행하지만, 직접 reserve(locale:)를 호출해 수동으로 처리할 수도 있음.
모듈 구성에서 필요한 에셋 다운로드를 시작.
1. 그 객체의 downloadAndInstall() 메서드를 호출하여 다운로드 및 설치 시작
2. assetInstallationRequest(supporting:)를 호출해 AssetInstallationRequest 인스턴스를 얻은 뒤, 다운로드가 완료될 때까지 기다림.
이미 시스템에 사전 설치되었거나, 다른 앱이 설치했거나, 이전에 동일한 모듈 구성을 사용했다면 다운로드가 즉시 완료될 수 있음.

(정리)

에셋이 한 번 다운로드되면, 앱을 재시작해도 유지되며 다른 앱과도 공유

시스템은 오랫동안 사용되지 않은 에셋에 대해 앱의 구독 상태를 해제할 수 있음.

Manage assets (에셋 관리하기)

앱에서 특정 Locale에 대한 에셋이 더 이상 필요하지 않은 경우, release(reservedLocale:)를 호출하여 해당 예약(reservation)을 해제할 수 있음.

시스템은 이후 필요에 따라 해당 에셋을 삭제.

Downloading and installing assets

assetInstallationRequest(supporting:)

에셋 다운로드를 시작하고 진행 상태를 모니터링하는 데 사용되는 설치 요청 객체를 반환
현재 상태가 .installed일 경우 더 이상 수행할 작업이 없다는 것을 의미하므로, nil을 반환

일부 에셋이 예약되지 않은 Locale을 필요로 한 경우 필요한 Locale을 자동으로 예약

단, 자동으로 예약하는 작업으로 인해 maximumReservedLocales을 초과하는 경우 throw로 에러를 던짐

위 상황에 대한 플로우 정리

이미 예약된 Locale: ["en-US"]
새로 필요한 Locale: ["en-US", "ko-KR"]
이 경우에는 "ko-KR"이 아직 준비되지 않았아서, inventory에 asset을 준비하는 코드를 명시적으로 작성하지 않아도 installation 시점에 알아서 reserve 해줌.

호출 메서드

public static func assetInstallationRequest(
    supporting modules: [any SpeechModule]
) async throws -> AssetInstallationRequest?

AssetInventory.Status

AssetInventory.Status는 우선순위가 존재하여, unsuppoted(1), suppoted(2), downloading(3), installed(4) 순서

숫자가 높을수록 우선순위 높음.

case downloading
- 시스템이 현재 에셋을 다운로드 중이거나 네트워크 혹은 배터리 등의 조건이 좋아지면 다운로드를 다시 시도할 예정
- 다운로드 진행상황은 progress를 통해 확인할 수 있음.
case installed
- 필요한 에셋이 이미 기기에 설치되어 있고 모듈을 바로 사용할 수 있는 상태
case supported
- 현재 구성(configuration)으로 모듈을 실행할 수는 있으나 필요한 에셋은 아직 다운로드해야 함.
- 해당 기기에서 지원 가능해서 설치해서 쓰면 됨.
case unsupported
- 이 설정(configuration)에서는 모듈을 전혀 사용할 수 없음.
- preset, configuration, locale 등 iOS 26 이상의 기기여도 해당 특정 조건을 만족하지 않는 경우에도 해담.

AssetInventory.status(forModules:)

모듈 목록에 대해서 상태를 반환.

해당 메서드는 배열로 modules를 받는데, 모듈들은 각각의 preset을 달리 가질 수 있어서 상태로 다를 수 있음.

public static func status(
    forModules modules: [any SpeechModule]
) async -> AssetInventory.Status

만약 목록에서 상태로 서로 다를 경우 우선순위가 가장 낮은 상태를 반환

AssetInventory.maximumReservedLocales

앱이 사용할 수 있는 Locale 개수로 해당 값은 reservedLocales가 가질 수 있는 최대 개수로, 기기의 저장공간 등에 따라 기기마다 다를 수 있음.

AssetInventory.reservedLocales

앱이 현재 보유하고 있는 asset locale 목록

모듈이 필요로 하는 에셋을 구독하기 전에, 먼저 해당 에셋의 로케일을 예약해야 하는데,

참고로 이 메서드가 반환하는 로케일은 reserve(locale:) 메서드에 전달한 로케일의 변형(variant)일 수 있음.

variant란?

reserve(locale: )에 en_US를 요청해도 시스템 내부에서 가장 적합한 Locale이 en_GB라고 판단하며, 실제 reserve 목록에서는 en_GB가 반환될 수 있다는 의미
즉, 내가 요청한 Locale과 시스템이 실제로 사용하는 Locale이 정확히 같지 않아도, 같은 언어 계열이면 variant(가장 가까운 대체 Locale)로 선택해서 반환한다는 의미.

AssetInventory.release(reservedLocale: Locale) async -> Bool

Asset Locale의 reservation을 해제

만약 Locale이 reserved되어 있지 않다면 false를 반환

AssetInventory.reserve(locale:)

이미 해당 Locale이 reserved 되었다면 false를 반환

입력한 Locale을 지원하는 에셋이 존재한다면 해당 에셋의 Locale을 reservedLocales 목록에 추가.

Throws (에러를 던지는 상황)

예약된 Locale 수가 maximumReservedLocales를 초과하게 되는 경우
해당 Locale을 지우너하는 Asset이 존재하지 않는 경우

AssetInstallationRequest

iOS 26.0+
iPadOS 26.0+
Mac Catalyst 26.0+
macOS 26.0+
visionOS 26.0+

에셋 선택을 설명하고, 다운로드하며 설치하는 객체

objc 유의

AssetInstallationRequest의 구현부

progress라는 프로퍼티를 가지고 있어서 진행 상황에 대해서 추적이 가능.

Overview

AssetInsllationRequest 타입의 인스턴스를 직접 생성하지 않고
AssetInventory.assetInstallationRequest(supporting:) 메서드를 통해 AssetInsllationRequest 객체를 얻음

시스템은 다운로드 및 설치 요청을 통합 관리하므로 여러 개의 인스턴스를 얻어 downloadAndInstall()을 여러번 호출해도 중복 다운로드가 발생하지 않음.

AssetInstallationRequest의 downloadAndInstall()

디바이스에 없는 에셋을 다운로드하고 설치

네트워크 문제나 기타 오류 등으로 인해 시스템이 즉시 에셋을 다운로드 할 수 없는 경우, 나중에 자동으로 다운로드를 시도

해당 메서드는 초기 다운로드 및 설치 시도가 성공하거나 실패한 시점에 반환

즉, 이후에 진행 상황이나 성공 여부 등은 status(forModules: ) 또는 다른 설치 요청 객체를 사용하여 모니터링.

시스템은 다운로드 및 설치 요청을 통합 관리하므로 중복 호출해도 중복 다운로드가 발생하지 않음.

func execute() async throws {
    let transcriber = SpeechTranscriber(locale: .current, preset: .progressiveTranscription)
    let requset = try await AssetInventory.assetInstallationRequest(supporting: [transcriber])
    try await requset?.downloadAndInstall()
}

(참고)

https://developer.apple.com/documentation/speech/assetinventory

SpeechAnalyzer

lgvv — Sat, 22 Nov 2025 15:43:54 +0900

SpeechAnalyzer

음성으로 입력된 오디오 콘텐츠를 다양한 방식으로 분석하고, analysis session을 관리

Actor로 정의되어 있음

Overview

Speech 프레임워크는 특정 유형의 analysis(분석) 및 transcription(받아쓰기) 기능을 제공하기 위해 analyzer에 추가할 수 있는 여러 모듈을 제공

대부분의 사용 사례에서는 음성을 텍스트로 변환하는 SpeechTranscriber 모듈만으로 충분.

SpeechAnalyzer 역할
- 관련 모듈을 보관
- 음성 오디오 입력을 수신
- 전체 분석 흐름을 제어
각 모듈의 역할
- 허용되는 입력 형태에 대한 가이던스를 제공
- 자체 분석 결과 또는 transcription 결과를 출력
비동기 기반으로 흐름 분석
- Analysis는 비동기로 수행.
- 입력, 출력, 세션 제어는 서로 분리되어 있고, 일반적으로 사용자가 생성하거나 세션을 생성하는 여러 작업을 통해 이루어짐.
- Objective-C API가 delegate 통해 결과를 전달하는 방식과 달리 Swift API는 AsnycSequence를 통해 결과를 제공
- 마찬가지로 음성 입력 역시도 데이터를 넣어주는 AsyncSequence 형태로 제공
입력 처리 제약사항
- analyzer는 한번에 하나의 입력 시퀀스만 분석할 수 있음.

Perform analysis

오디보 파일 혹은 스트림에 대해서 분석하려면 아래의 단계에 따라서 진행

필요한 모듈을 생성하고 구성
관련 에셋이 설치되어 있거나 이미 존재하는지 확인. (AssetInventory)
음성 오디오를 제공할 수 있는 입력 시퀀스를 생성
생성한 모듈과 입력 시퀀스로 분석기를 생성하고 구성
오디오를 공급.
분석을 시작.
결과를 처리.
필요 시 분석을 종료.

샘플코드

아래는 스텝에 따라 진행되는 샘플 코드

//
//  Transcriber.swift
//  TranscriberExample
//
//  Created by Geon Woo lee on 11/21/25.
//

import Foundation
import Speech

final class Transcriber {
    private var transcriber: SpeechTranscriber!
    private var inputSequence: AsyncStream<AnalyzerInput>!
    private var inputBuilder: AsyncStream<AnalyzerInput>.Continuation!
    
    private var audioFormat: AVAudioFormat!
    private var analyzer: SpeechAnalyzer!
    
    private var lastSampleTime: CMTime?
    
    /// Create and configure the necessary modules.
    func createModules() async {
        // Step 1: Modules
        guard let locale = await SpeechTranscriber.supportedLocale(
            equivalentTo: Locale.current
        ) else {
            return
        }
        let transcriber = SpeechTranscriber(
            locale: locale,
            preset: .transcription
        )
        self.transcriber = transcriber
    }

    /// Ensure the relevant assets are installed or already present. See AssetInventory.
    func ensureAssetsArePresent() async throws {
        // Step 2: Assets
        if let installationRequest = try await AssetInventory.assetInstallationRequest(
            supporting: [transcriber]
        ) {
            try await installationRequest.downloadAndInstall()
        }

    }

    /// Create an input sequence you can use to provide the spoken audio.
    func createInputSequence() {
        // Step 3: Input sequence
        let (inputSequence, inputBuilder) = AsyncStream.makeStream(of: AnalyzerInput.self)
        self.inputSequence = inputSequence
        self.inputBuilder = inputBuilder
    }
    
    /// Create and configure the analyzer with the modules and input sequence.
    func createAnalyzer(with inputSequence: SFSpeechAudioBufferRecognitionRequest) async {
        // Step 4: Analyzer
        let audioFormat = await SpeechAnalyzer.bestAvailableAudioFormat(compatibleWith: [transcriber])
        let analyzer = SpeechAnalyzer(modules: [transcriber])
        
        self.audioFormat = audioFormat
        self.analyzer = analyzer
    }
    
    /// Supply audio.
    func supplyAudio(_ audio: Data, to analyzer: SFSpeechRecognizer) {
        // Step 5: Supply audio
        Task {
            
//            while /* audio remains */ {
//                /* Get some audio */
//                /* Convert to audioFormat */
//                let pcmBuffer = /* an AVAudioPCMBuffer containing some converted audio */
//                let input = AnalyzerInput(buffer: pcmBuffer)
//                inputBuilder.yield(input)
//            }
            
            inputBuilder.finish()
        }

    }

    /// Start analysis.
    func stratAnalysis(using recognizer: SFSpeechRecognizer) async throws {
        // Step 6: Perform analysis
        let lastSampleTime = try await analyzer.analyzeSequence(inputSequence)
        self.lastSampleTime = lastSampleTime
    }

    /// Act on results.
    func actOnResults(_ results: [SFSpeechRecognitionResult]) {
        // Step 7: Act on results
        Task {
            do {
                for try await result in transcriber.results {
                    let bestTranscription = result.text // an AttributedString
                    let plainTextBestTranscription = String(bestTranscription.characters) // a String
                    print(plainTextBestTranscription)
                }
            } catch {
                /* Handle error */
            }
        }
    }

    /// Finish analysis when desired.
    func finishAnalysis() async throws {
        // Step 8: Finish analysis
        if let lastSampleTime {
            try await analyzer.finalizeAndFinish(through: lastSampleTime)
        } else {
            await analyzer.cancelAndFinishNow()
        }
    }
}

Analyze audio files (오디오 파일 분석)

AVAudioFile 객체로 표현된 하나 이상의 오디오 파일을 분석하기 위해서는

analyzeSequence(from:) 또는 start(inputAudioFile:finishAfterFile:)와 같은 메서드를 호출

또는 파일 파라미터를 갖는 초기화 메서드 중 하나를 사용해 analyzer를 통해 생성할 수 있음.

analyzeSequence(from:) 또는 start(inputAudioFile:finishAfterFile:) 메서드는 파일을 자동으로 지원되는 오디오 형식으로 변환하고, 파일 전체를 처리

하나의 파일 분석 후 세션을 종료하려면 finishAfterFile 매개변수에 true를 전달하거나 제공된 finish 메서드 중 하나를 호출.

그렇지 않으면 기본적으로 분석기는 결과 스트림을 종료하지 않고, 추가 오디오 파일이나 버퍼를 기다림.

분석 세션은 각 파일 후 오디오 타임라인을 초기화하지 않으며, 다음 오디오는 이전 파일이 끝난 직후에 이어진 것으로 간주.

Analyze audio buffers (오디오 버퍼 분석)

오디오 버퍼를 직접 분석하려면 버퍼를 지원되는 오디오 형식으로 변환해야 하며, 변환은 즉시(on-the-fly) 또는 사전에 미리 수행할 수 있음.

bestAvailableAudioFormat(compatibleWith:) 또는 개별 모듈의 availableCompatibleAudioFormats 메서드를 사용하여 변환할 형식을 선택할 수 있음.

각 오디오 버퍼에 대해 AnalyzerInput 객체를 생성하고, 이를 사용자가 만든 입력 시퀀스에 추가

생성한 입력 시퀀스를 analyzeSequence(_:), start(inputSequence:) 또는 분석기 초기화 메서드의 유사한 파라미터에 전달

오디오 스트림의 일부를 건너뛰고 싶다면, 입력 시퀀스에서 건너뛰고자 하는 버퍼를 제외하면 됨.

이후 나중에 분석을 재개할 때, 각 모듈의 결과가 건너뛴 오디오를 고려하도록 시간 코드를 맞출 수 있음.

이를 위해, 이후 버퍼가 오디오 스트림 내에서 시작되는 시간 코드를 해당 AnalyzerInput 객체의 bufferStartTime 파라미터로 전달.

Analyze autonomously (자율적으로 분석하기)

일반적으로는 analyzeSequence(_:) 또는 analyzeSequence(from:) 메서드를 사용해 분석을 수행하는 것이 좋음.

이러한 메서드는 Swift의 구조적 동시성(Structured Concurrency)과 잘 어울림.

Analyzer가 자체적으로 관리하는 작업 내에서 새로운 오디오 입력이 도착하는 즉시 자동으로 분석을 진행하도록 하고 싶을 수도 있음.

이 기능을 사용하려면 입력 시퀀스나 파일 파라미터가 포함된 초기화 메서드 중 하나를 사용해 Analyzer를 생성하거나 start(inputSequence:) 또는 start(inputAudioFile:finishAfterFile:) 메서드를 호출

입력이 끝날 때 분석을 종료하려면 finalizeAndFinishThroughEndOfInput()을 호출

현재 입력 분석을 끝내고 다른 입력에 대한 분석을 새로 시작하려면 start 계열 메서드를 다시 호출하면 됨.

결과 처리와 타이밍 제어 (Control processing and timing of results)

각 모듈은 주기적으로 결과를 전달하지만, 외부 신호나 특정 타이밍에 맞춰 결과의 처리 및 전달을 수동으로 동기화할 수도 있음.

특정 시간 코드(time-code)까지의 결과를 전달하려면 finalize(through:)를 호출.

더 이상 필요하지 않은 시간 이전의 결과 처리를 취소하려면 cancelAnalysis(before:)를 호출.

반응성 향상하기 (Improve responsiveness)

기본적으로 analyzer 모듈들은 필요한 시스템 리소스를 지연 로드(lazy load하며 해제될 때 해당 리소스를 언로드(unload)함.

모듈을 설정한 후 analyzer를 미리 준비(preheat)하여 시스템 리소스를 선제적으로 로드하려면 prepareToAnalyze(in:)를 호출.

이 작업은 모듈이 초기 결과를 반환하는 속도를 향상시킬 수 있음.

다른 분석기 인스턴스가 나중에 재사용할 수 있도록 리소스 언로드를 지연하거나 방지하려면, SpeechAnalyzer.Options.ModelRetention 옵션을 선택하고 해당 옵션이 포함된 SpeechAnalyzer.Options 객체로 analyzer를 생성

분석 작업의 우선순위를 설정하려면, 우선순위 값이 지정된 SpeechAnalyzer.Options 객체를 사용해 analyzer를 생성

또한, 일부 모듈에서는 반응성을 향상시키는 추가 옵션을 제공하기도 함.

분석 종료하기 (Finish analysis)

분석 세션을 종료하려면, 분석기의 finish 계열 메서드나 관련 파라미터를 사용하거나, 분석기 인스턴스를 해제(deallocate)해야 함.

분석 세션이 finished 상태로 전환되면 다음과 같은 변화가 발생.

분석기는 입력 시퀀스로부터 더 이상 새로운 입력을 받지 않음.
대부분의 메서드는 더 이상 동작하지 않으며, 특히 새로운 입력 시퀀스나 모듈을 받아들이지 않음.
모듈의 결과 스트림은 종료되며, 모듈은 추가 결과를 발행하지 않음.
단, 앱은 이미 발행된 결과들에 대해서는 계속 반복(iterate)하여 읽을 수 있음.

참고 (Note)

AsyncStream.Continuation.finish()처럼 입력 시퀀스를 종료하는 메서드를 통해 입력 스트림을 끝낼 수는 있지만,

입력 시퀀스를 종료하는 것만으로는 분석 세션이 finished 상태가 되지 않음.

입력 시퀀스가 끝난 후에도, 다른 입력 시퀀스를 제공하여 세션을 계속 진행할 수 있음.

즉, 분석 세션의 종료와 스트림의 종료를 다르게 봐야 한다는 의미.

에러 처리하기 (Respond to errors)

분석기 또는 모듈의 결과 스트림에서 오류가 발생, 분석 세션은 앞서 설명한 것처럼 finished 상태로 전환

이때 동일한 오류(또는 CancellationError)가 대기 중인 모든 메서드와 결과 스트림에서 다시 throw

SpeechTranscriber 정리 + DictationTranscriber

lgvv — Sat, 22 Nov 2025 15:40:24 +0900

SpeechTranscriber 정리 + DictationTranscriber

SpeechTranscriber, DictationTranscriber 각각에 대해서 정리하고, SpeechTranscriber의 속성과 구현을 하나씩 확인.

SpeechTranscriber
- Overview
- Check device support
DictationTranscriber
- Overview
- Improve accuracy
SpeechTranscriber와 DictationTranscriber 비교 정리
SpeechTranscriber 자세히 보기
- isAvailable과 supportedLocales 프로퍼티 정의
- Configuring transcription
  - SpeechTranscriber.ReportingOption
  - SpeechTranscriber.ResultAttributeOption
  - SpeechTranscriber.TranscriptionOption
- Checking locale support
  - SpeechTranscriber.InstalledLocales
  - SpeechTranscriber.supportedLocales
  - SpeechTranscriber.supportedLocale(equivalentTo:)
- SpeechTranscriber.Result
  - Overview
  - Getting transcriptions
    - alternatives
    - text
  - Working with transcriptions
    - AttributeScopes.SpeechAttributes.TimeRangeAttribute
    - AttributeScopes.SpeechAttributes.ConfidenceAttribute
    - rangeOfAudioTimeRangeAttributes(intersecting:)
- SpeechTranscriber.Preset
  - Overview
  - Standard presets
    - transcription
    - transcriptionWithAlternatives
    - timeIndexedTranscriptionWithAlternatives
    - progressiveTranscription
    - timeIndexedProgressiveTranscription
  - Getting preset properties
    - attributeOptions
    - reportingOptions
    - transcriptionOptions
SpeechTranscriber.Preset을 사용하는 이유

SpeechTranscriber

iOS 26.0+
iPadOS 26.0+
Mac Catalyst 26.0+
macOS 26.0+
visionOS 26.0+

일상적인 대화와 일반적인 용도에 적합한 음성 - 텍스트 변환 모듈

SpeechTranscriber Overview

여러 개의 Transcriber 인스턴스는 특정 측면에서 비슷하게 구성되어 있다면 동일한 엔진 인스턴스와 모델 공유할 수 있음.

SpeechTranscriber Check device support

현재 사용하는 디바이스가 SpeechTranscriber에서 사용하는 음성-텍스트(speech-to-text) 모델을 지원하는지 확인하려면 isAvailable 또는 supportedLocales 속성을 통해 확인

지원하지 않는 경우, 해당 기능을 비활성화하거나 대신 DictationTranscriber를 사용하는 것을 고려.

DictationTranscriber

iOS 26.0+
iPadOS 26.0+
Mac Catalyst 26.0+
macOS 26.0+
visionOS 26.0+

시스템 받아 쓰기 기능과 유사하여, 구형 기기와도 호환되는 음성-텍스트(speech-to-text) 모듈

DictationTranscriber Overview

해당 Transcriber는 speech-to-text ML 모델, 혹은 SFSpeechRecognizer가 온디바이스(On-Device) 모드로 설정되었을 때 사용하는 모델과 동일한 모델을 활용

DictationTranscriber는 SFSpeechRecognizer가 네트워크 연결을 통해서만 지원하는 언어 또는 로케일은 지원하지 않음.

DictationTranscriber Improve accuracy

특정 단어에 인식 편향을 주거나 사용자가 직접 정의한 어휘를 제공하거나 Transcriber의 알고리즘을 조정해 음성 인식 정확도를 향상시킬 수 있음.

To bias recognition towards certain words (특정 단어에 인식 편향)
- AnalysisContext 객체를 생성한 뒤 특정 단어들을 contextualStrings 프로퍼티에 추가.
- 그 이후로 SpeechAnalyzer 객체를 생성하거나 기존 Analyzer에 context 프로퍼티에 설정
To supply custom vocabulary (직접 정의한 어휘 제공)
- SFSpeechLanguageModel 객체를 생성하고 Transciber에 customizedLanguage(modelConfiguration:)에 옵션으로 구성하여 해당 모델을 사용하도록 설정
To adjust the transcriber’s algorithm (알고리즘을 조정)
- DictationTranscriber.ContentHint 파라미터로 Transcriber를 구성
- 예를 들어서 먼 거리에서 들리는 음성의 정확도를 높이고 싶다면 farField에 힌드를 사용할 수 있음.

SpeechTranscriber와 DictationTranscriber 비교 정리

DictationTranscriber는 SFSpeechRecognizer(iOS 10.0+)와 동일한 ML 모델을 사용해서 성능도 이와 동일하고, SpeechTranscriber에서 아직 언어를 지원하지 않는 경우에 받아쓰기 형태로 사용.

회사 서비스에서 사용하기엔 성능이 안좋다고 느낌.

SFSpeechRecognizer를 사용할 때는 Siri 권한 요청부터 오디오 재생 시간을 1분으로 제한하는 등 여러가지 제약사항이 존재하는데, DictationTranscriber는 SFSpeechRecognizer를 래핑해 둔 정도.

SpeechTranscriber 자세히 보기

SpeechTranscriber는 SpeechModule과 LocaleDependentSpeechModule을 채택하고 있음.

SpeechModule은 나중에 AssetInventory에서 필요한 에셋을 조회할 때 해당 프로토콜을 채택한 객체들로 조회

isAvailable과 supportedLocales 프로퍼티 정의

(참고)

isAvailable는 시뮬레이터에서도 하드웨어 및 기기 OS조건이 맞으면 true로 반환.

supportedLocales는 시뮬레이터에서는 항상 빈 배열로 나타나서 SpeechTranscriber에서는 사용할 수 없는 것으로 보임.

/**
 모듈이 현재 기기의 하드웨어 및 기능 조건에서 사용 가능한지를 나타내는 Boolean 값입니다.
 */
public static var isAvailable: Bool { get }

/**
 변환기가 전사(transcribe)할 수 있는 로케일(locale) 목록입니다.  
 설치되어 있지 않지만 다운로드 가능한 로케일도 포함됩니다.
 
 만약 기기가 변환기를 지원하지 않으면 이 배열은 비어 있습니다.
 */
public static var supportedLocales: [Locale] { get async }

SpeechTranscriber.ReportingOption

transcriber의 결과 전달과 관련된 옵션

case .alternativeTranscriptions

가장 가능성이 높은 transcriptions 결과 외에도 대체 transcriptions를 포함.
음성을 텍스트로 변환할 때 가장 정확하다고 판단한 한 가지 결과는 주전사 결과이고, 음성 입력에 대해 다른 가능성이 있는 해석들도 제공
장점: 후처리에서 문맥이나 사용자의 의도에 맞춰 더 정확하게 선택 가능
단점: 결과가 많아져 처리해야 할 데이터가 늘어남..

case .fastResults

transcriber가 더 빠르게 반응하도록 조정
각 결과를 빠르게 내기 위해서 참고하는 이전 context의 양을 줄이며, 음성 스트림의 작은 구간(window 및 chunk)만을 사용해서 처리
장점: 처리 속도가 더 빨라짐. (즉, 처음 결과가 더 빠르게 나옴)
단점: 이전 context를 충분히 참고하지 않기 때문에 정확도가 낮아질 수 있음.

case .volatileResults

최종 결과(finalized result) 외에도 잠정 결과(tentative result)를 제공.
즉, 전사가 완료되기 전에도 중간 단계의 텍스트를 미리 받아볼 수 있으며, 같은 오디오 구간(audio range)에 대해 여러번 중간 결과를 전달해 점점 전사 정확도를 높이면서 최종 결과로 수렴.
목적: 실시간 피드백을 제공가능하며 중간 결과를 활용한 UI 업데이트 가능.
효과: 전사가 완료되기 전에 텍스트를 미리 보여줄 수 있음.
단점: 중간 결과가 최종과 다를 수 있어서 최종 결과와 혼동하지 않도록 처리가 필요.

SpeechTranscriber.ResultAttributeOption

해당 옵션은 transcription 결과가 어떻게 표현할지를 제어하는 옵션

case .audioTimeRange

타임코드(time-code) 정보를 전사 결과 AttributedString에 포함시킬 것인지를 결정하는 설정
Foundation/AttributeScopes/SpeechAttributes/TimeRangeAttribute 타입
Usage
- 자막(SRT, VTT) 생성
- 먼저 만든 단어와 싱크 유지
- 탭 하면 원하는 오디오 위치로 이동하는 인터랙션

case .transcriptionConfidence

전사 결과에 신뢰도(confidence)를 포함시킬 것인지 결정
These are Foundation/AttributeScopes/SpeechAttributes/ConfidenceAttribute 타입
Usage
- 신뢰도 기능 UX 제공 (신뢰도가 낮은 부분은 회색처리 하거나 정확하지 않을 수 있음 안내)
- 후처리 자동화 (특정 신뢰도 이하 단어를 자동 보정 모델에 보내기)
- 자막 품질 개선 (저신뢰 단어는 별도 처리)

SpeechTranscriber.TranscriptionOption

전사된 문자열(plain text)를 어떤 형태로 출력될지를 설정하는 것들.

case .etiquetteReplacements

특정 단어와 구문을 편집된(가려진) 형태로 대체.
해당 옵션이 활성화 될 경우에 욕설로 인식된 구문은 별표(*)로 대체되어 전사됨.

SpeechTranscriber.InstalledLocales

현재 기기에 설치된 Locales을 기준으로 transcribe할 수 있는 목록 리스트

SpeechTranscriber.supportedLocales

기기에 설치되지 않았지만 다운로드 가능한 Locale을 포함하여 transcribe할 수 있는 목록 리스트

SpeechTranscriber.supportedLocale(equivalentTo:)

모듈이 지원하는 Locale 중에서 지정한 Locale과 동등한 Locale을 반환

Parameter
- 임의의 Locale
ReturnValue
- 지원되는 Locale 목록에서 동등한 Locale을 반환하여, 해당하는 Locale이 없으면 nil을 반환

Locale.current와 같은 임의의 Locale이 있을 때, 해당 모듈이 지원하는 Locale 중에서 어떤 것이 그 Locale과 동등한지 확인할 때 사용

정확히 일치하는 Locale이 없는 경우에는 해당 메서드는 근사치(near-equivalent)를 반환

즉, 같은 Locale.LanguageCode는 같은 값을 가지지만 Locale.Region 값이 다른 Locale로 가능하면 이미 설치된 Locale이 우선됨.

따라서 color를 colour처럼 예상하는 것과 다른 결과를 생성할 수도 있음.

해당 메서드를 사용하더라도, 앱은 사용자가 지원되는 Locale 목록에서 직접 Locale을 선택하여 수정할 수 있는 기능을 제공하는 것이 바라직.

SpeechTranscriber.Result

전사된 구문이나 구절로, 구문은 순서대로 전달.

Overview
- 전사기가 volatile results 옵션으로 구성된 경우, 각 구문은 최종 결과로 확정되기 전까지 전사 정확도가 점점 향상되면서, 한 번 이상 반복해서 전달될 수 있음.
alternatives
- 오디오 구간에 대한 모든 가능한 대체 해석을 포함하여 가능성 순으로 내림차순으로 정렬
- 배열은 비어 있지는 않으나, 빈 문자열이 포함될 수 있음.
- 빈 문자열의 경우에는 해당 오디오 구간에 전사가 없는 대체 결과를 나타냄.
  - 대체 결과를 받기 위해서는SpeechTranscriber.ReportingOption.alternativeTranscriptions를 설정해야 함.
text
- 해당 오디오 구간에서 가장 가능성이 높은 전사 결과 (most likley interpertation)
- 여기서는 빈 문자열은 해당 오디오에 인식 가능한 음성이 없음을 나타내고, volatile range의 결과에서는 이 구간의 이전의 결과가 무효화 되었음을 의미
- 이 값은 alternatives 배열의 첫 번째 요소(가장 가능성이 높은 결과)와 동일.
AttributeScopes.SpeechAttributes.TimeRangeAttribute
- 연관된 전사 텍스트에 대응하는 원본 오디오의 시간 범위
- 원본 오디오에 특정 시간 범위에 해당하는 텍스트를 찾으려면 rangeOfAudioTimeRangeAttributes(intersecting: )메서드 사용
AttributeScopes.SpeechAttributes.ConfidenceAttribute
- 연관된 전사 텍스트의 신뢰도로 0에서 1사이의 값.
func rangeOfAudioTimeRangeAttributes(intersecting timeRange: CMTimeRange) -> Range<AttributedString.Index>?
- 해당 메서드는 주어진 시간 범위를 수신 객체의AttributeScopes.SpeechAttributes.TimeRangeAttribute와 비교.
- 해당 SpeechTranscriber또는 DictationTranscriber 모듈의 volatile 또는 finalized 결과를 추적하는 AttributedString을 업데이트할 때 유용하게 사용할 수 있음.

SpeechTranscriber.Preset

미리 정의된 transcriber의 구성

Overview
- transcriber는 preset을 사용하여 구성할 수 있고, 해당 속성 값을 수정한 뒤 수정된 값으로 transcriber를 구성할 수 있음.
- 이 타입을 확장하여 사용자 정의의 preset을 직접 만들 수도 있음.
- preset을 반드시 사용할 필요는 없어서 transcriber를 사용하여 커스터마이징할 수도 있음.

Preset을 이용하여 SpeechTranscriber를 구성하는 샘플 코드

timeIndexedTranscriptionWithAlternatives 프리셋을 기반으로 transcriber를 구성하고 etiquette filtering을 추가하고 alternative transcription을 제거한 경우를 보여줌.

let preset = SpeechTranscriber.Preset.timeIndexedTranscriptionWithAlternatives
let transcriber = SpeechTranscriber(
    locale: Locale.current,
    transcriptionOptions: preset.transcriptionOptions.union([.etiquetteReplacements])
    reportingOptions: preset.reportingOptions.subtracting([.alternativeTranscriptions])
    attributeOptions: preset.attributeOptions
)

아래는 미리 구성된 프리셋과 해당 구성 설정

transcription
- 기본적이고 정확한 전사를 위한 구성
transcriptionWithAlternatives
- 편집 제안 기능이 포함된 전사를 위한 구성
timeIndexedTranscriptionWithAlternatives
- 원본 오디오와 교차 참조된 편집 제안 기능 전사를 위한 구성
progressiveTranscription
- 실시간 오디오 즉시 전사를 위한 구성
timeIndexedProgressiveTranscription
- 스트림 타임코드와 교차 참조된 실시간 오디오 즉시 전사를 위한 구성

Preset	volatileResults	fastResults	alternativeTranscriptions	audioTimeRange
transcription	NO	NO	NO	NO
transcriptionWithAlternatives	NO	NO	Yes	NO
timeIndexedTranscriptionWithAlternatives	NO	NO	Yes	Yes
progressiveTranscription	Yes	Yes	NO	NO
timeIndexedProgressiveTranscription	Yes	Yes	NO	Yes

attributeOptions
- 이 프리셋에 적합한 transcriber 속성 관련 옵션
reportingOptions
- 이 프리셋에 적합한 transcriber 결과 전달 옵션
transcriptionOptions
- 이 프리셋에 적합한 전사 텍스트 관련 옵션

SpeechTranscriber.Preset을 사용하는 이유

SpeechTranscriber의 이니셜라이저 코드를 보면 아래와 같이 2개의 생성자가 존재

Preset을 통해 여러 옵션들에 대한 구성을 미리 정해둔 구성 세트로 필요할 때마다 다양한 옵션을 묶어서 한번에 제공.

Transcriber에는 iOS 26 최신을 기준으로 여러 옵션이 존재.

결과 전달 방식: 즉시 전달할지, 최종 결과만 전달할지
텍스트 옵션: 비속어 필터링
속성 옵션: 타임스탬프, 단어별 신뢰도, 대체 전사 등

이 옵션들을 매번 하나씩 설정하는 대신에 프리셋을 선택하여 미리 세팅된 상태로 Transcriber를 사용할 수 있음.

(참고)

https://developer.apple.com/documentation/speech/speechtranscriber

SpeechAnalyzer | Apple Developer Documentation

Analyzes spoken audio content in various ways and manages the analysis session.

developer.apple.com

https://developer.apple.com/documentation/speech/dictationtranscriber

DictationTranscriber | Apple Developer Documentation

A speech-to-text transcription module that’s similar to system dictation features and compatible with older devices.

developer.apple.com

적절한 하이퍼파라미터 값 찾기 및 구현 실습

lgvv — Wed, 19 Nov 2025 00:32:12 +0900

적절한 하이퍼파라미터 값 찾기 및 구현 실습

신경망에는 하이퍼파라미터가 다수 등장.

여기서 말하는 하이퍼파라미터는 뉴런 수, 배치 크기, 매개변수 갱신 시의 학습률, 가중치 감소 등이 존재.

적절한 값을 설정하지 못할 경우 모델 성능이 크게 떨어지기도 함.

하이퍼파라미터 값은 매우 중요하지만, 그 값을 결정하기까지는 일반적으로 많은 시행착오를 겪음.

검증 데이터

데이터셋을 훈련 데이터와 시험 데이터로 분리.

하이퍼파라미터의 성능을 평가할 때는 시험 데이터를 사용해서는 안됨.

시험 데이터를 사용하여 하이퍼파라미터를 조정하면 하이퍼파라미터 값이 시험 데이터에 오버피팅되기 때문

하이퍼파라미터를 조정할 때는 하이퍼파라미터 전용 확인 데이터가 필요.

하이퍼파라미터 조정 데이터를 일반적으로 검증 데이터라고 부름
하이퍼파라미터의 적절성을 평가하는 데이터.

용어 정리

훈련 데이터: 매개변수 학습

검증 데이터: 하이퍼파라미터 성능 평가

시험 데이터: 신경망의 범용 성능 평가

하이퍼파라미터 최적화

최적의 값이 존재하는 범위를 조금씩 줄여가는 형태로 접근.

범위를 조금씩 줄이려면 우선 대략적인 범위를 설정하고 그 범위에서 무작위로 하이퍼파라미터 값을 골라낸(샘플링)한 후 그 값으로 정확도 평가.

하이퍼파라미터 최적화에서는 그리드 서치 같은 규치적인 탐색 보다는 무작위로 샘플링해 탐색하는 편이 더 좋은 결과를 낸다고 알려져 있음.

하이퍼파라미터 값을 설정할 때는 대략적으로 지정하는 것이 효과적으로 0.001에서 1.000 사이로 설정하며, 매우 오랜 시간이 걸림.

따라서 나쁠 듯한 값은 일찍 포기하는 것이 좋음.

학습을 위한 에폭을 작게 유지해서 1회 평가에 걸리는 시간을 단축하는 것이 효과적.

0단계: 하이퍼파라미터 값 범위 설정
1단계: 설정된 범위에서 하이퍼파라미터의 값을 무작위로 추출
2단계: 1단계에서 샘플링한 하이퍼파라미터 값을 사용하여 학습하고, 검증 데이터로 정확도를 평가 (에폭을 작게)
1단계와 2단계를 특정 횟수 반복하여 그 정확도의 결과를 보고 하이퍼파라미터의 범위를 좁힘.

하이퍼파라미터 최적화 방법은 실용적인 방법. 하지만 과학이기보단 직관과 지혜에 의존.

베이즈 최적화는 베이즈 정리를 중심으로 한 수학 이론을 구사하여 더 엄밀하고 효율적으로 최적화를 수행.

하이퍼파라미터 최적화 샘플 코드

훈련 데이터: 매개변수 학습

import torch
import torch.nn as nn
import torch.nn.functional as F
import torch.optim as optim
import torchvision
import torchvision.transforms as transforms
import numpy as np
import random

# 재현성을 위한 시드 설정
torch.manual_seed(42)
np.random.seed(42)
random.seed(42)

print("라이브러리 임포트 완료 및 시드 설정 완료.")

# 데이터 로드 (MNIST 사용)
transform = transforms.Compose([transforms.ToTensor(), transforms.Normalize((0.5,), (0.5,))])
trainset = torchvision.datasets.MNIST(root='./data', train=True, download=True, transform=transform)
testset = torchvision.datasets.MNIST(root='./data', train=False, download=True, transform=transform)

# 모델 정의
class SimpleMLP(nn.Module):
    def __init__(self):
        super(SimpleMLP, self).__init__()
        self.fc1 = nn.Linear(784, 128)
        self.fc2 = nn.Linear(128, 64)
        self.fc3 = nn.Linear(64, 10)

    def forward(self, x):
        x = x.view(-1, 784)
        x = F.relu(self.fc1(x))
        x = F.relu(self.fc2(x))
        x = self.fc3(x)
        return x

print("데이터셋 로드 및 모델 클래스 정의 완료.")

def train_and_evaluate(params):
    # 하이퍼파라미터 추출
    lr = params['learning_rate']
    batch_size = params['batch_size']
    optimizer_name = params['optimizer']
    num_epochs = 5 # 최적화 탐색은 짧은 Epoch으로 빠르게 수행

    # 데이터 로더 설정 (배치 크기 적용)
    trainloader = torch.utils.data.DataLoader(trainset, batch_size=batch_size, shuffle=True)
    testloader = torch.utils.data.DataLoader(testset, batch_size=batch_size, shuffle=False)
    
    # 모델 및 최적화 함수 설정
    model = SimpleMLP()
    criterion = nn.CrossEntropyLoss()
    
    if optimizer_name == 'Adam':
        optimizer = optim.Adam(model.parameters(), lr=lr)
    elif optimizer_name == 'SGD':
        optimizer = optim.SGD(model.parameters(), lr=lr)
    else:
        raise ValueError("Unknown optimizer")

    # 학습 루프
    for epoch in range(num_epochs):
        model.train()
        for data, targets in trainloader:
            scores = model(data)
            loss = criterion(scores, targets)
            optimizer.zero_grad()
            loss.backward()
            optimizer.step()

    # 테스트 정확도 평가
    model.eval()
    num_correct = 0
    num_samples = 0
    with torch.no_grad():
        for x, y in testloader:
            scores = model(x)
            _, predictions = scores.max(1)
            num_correct += (predictions == y).sum()
            num_samples += predictions.size(0)
    
    accuracy = (num_correct / num_samples * 100).item()
    return accuracy

# 탐색할 하이퍼파라미터 공간 정의
hyperparameter_space = {
    'learning_rate': [0.01, 0.001, 0.0001],
    'batch_size': [32, 64, 128],
    'optimizer': ['Adam', 'SGD']
}

# 탐색 횟수 설정
NUM_TRIALS = 10
best_accuracy = 0
best_params = {}
results = []

print(f"--- 하이퍼파라미터 랜덤 서치 시작 (시도 횟수: {NUM_TRIALS}) ---")

for i in range(NUM_TRIALS):
    # 무작위 조합 선택
    params = {
        'learning_rate': random.choice(hyperparameter_space['learning_rate']),
        'batch_size': random.choice(hyperparameter_space['batch_size']),
        'optimizer': random.choice(hyperparameter_space['optimizer'])
    }
    
    print(f"\n시도 {i+1}/{NUM_TRIALS}: {params}")
    
    # 학습 및 평가 실행
    try:
        accuracy = train_and_evaluate(params)
        results.append({'params': params, 'accuracy': accuracy})
        print(f"-> 정확도: {accuracy:.2f}%")
        
        # 최고 성능 갱신
        if accuracy > best_accuracy:
            best_accuracy = accuracy
            best_params = params
            
    except Exception as e:
        print(f"오류 발생: {e}")
        continue

print("\n--- 탐색 완료 ---")
print(f"최고 정확도: {best_accuracy:.2f}%")
print(f"최적 파라미터: {best_params}")

아래는 샘플 코드에 대한 결과 해석

라이브러리 임포트 완료 및 시드 설정 완료.
데이터셋 로드 및 모델 클래스 정의 완료.
--- 하이퍼파라미터 랜덤 서치 시작 (시도 횟수: 10) ---

시도 1/10: {'learning_rate': 0.0001, 'batch_size': 32, 'optimizer': 'Adam'}
-> 정확도: 95.09%

시도 2/10: {'learning_rate': 0.0001, 'batch_size': 64, 'optimizer': 'Adam'}
-> 정확도: 94.30%

시도 3/10: {'learning_rate': 0.01, 'batch_size': 32, 'optimizer': 'Adam'}
-> 정확도: 92.79%

시도 4/10: {'learning_rate': 0.0001, 'batch_size': 128, 'optimizer': 'Adam'}
-> 정확도: 93.07%

시도 5/10: {'learning_rate': 0.0001, 'batch_size': 64, 'optimizer': 'Adam'}
-> 정확도: 93.72%

시도 6/10: {'learning_rate': 0.01, 'batch_size': 32, 'optimizer': 'Adam'}
-> 정확도: 93.64%

시도 7/10: {'learning_rate': 0.01, 'batch_size': 128, 'optimizer': 'Adam'}
-> 정확도: 94.84%
...

--- 탐색 완료 ---
최고 정확도: 95.09%
최적 파라미터: {'learning_rate': 0.0001, 'batch_size': 32, 'optimizer': 'Adam'}
Output is truncated. View as a scrollable element or open in a text editor. Adjust cell output settings...

lgvv98

SwiftUI의 새로운 기능 (Explore related documentation, sample code, and more) -wwdc25

SwiftUI의 새로운 기능 (Explore related documentation, sample code, and more)

목차

Make the new design shine

Framework foundations

SwiftUI across the system

defer로 인해 lock의 범위가 넓어져 발생한 문제 분석

defer로 인해 lock의 범위가 넓어져 발생한 문제 분석

문제가 발생하는 코드 예시

lock은 상태만 보호하기

기기별 RAM 용량에 따른 이미지 동적 캐시 사이즈 설계

기기별 RAM 용량에 따른 이미지 동적 캐시 사이즈 설계

왜 동적 설정이 필요할까?

전체 코드

HTTPURLResponse.allHeaderFields 파싱 시 NSNumber 헤더 누락 문제

HTTPURLResponse.allHeaderFields 파싱 시 NSNumber 헤더 누락 문제

코드 예시

빠르게 링크: 빌드 및 실행 시간 개선 (Link fast: Improve build and launch times) - WWDC22

빠르게 링크: 빌드 및 실행 시간 개선 (Link fast: Improve build and launch times) - WWDC22

목차

Xcode 빌드에서의 병렬 처리에 대한 오해 해소(Demystify parallelization in Xcode builds) - WWDC22

Xcode 빌드에서의 병렬 처리에 대한 오해 해소(Demystify parallelization in Xcode builds) - WWDC22

목차

swift rethrows

swift rethrows

코드 샘플

AVAudioEngine, AVAudioNode 정리

AVAudioEngine, AVAudioNode 정리

목차

AVAudioEngine

오디오 렌더링이란?

Overview

Create an Engine for Audio File Playback

AVAudioNode

Overview

Configuring an Input Format Bus

Creating an Output Format Bus

Installing and Removing an Audio Tap

Getting the Audio Engine for the Node

Getting the Latest Node Render Time

Getting Audio Node Properties

Resetting the Audio Node

Constants

AVAudioFormat 정리

AVAudioFormat 정리

목차

AVAudioFormat

Overview

AVAudioFormat의 프로퍼티들

AVAudioFormat과 AudioStreamBasicDescription의 비교 정리

Channel과 ChannelLayout의 차이

AVAudioCommonFormat 정리

AudioStreamBasicDescription 정리

AudioStreamBasicDescription 정리

목차

AudioStreamBasicDescription

Overview

구조체의 모든 필드를 0으로 초기화하는 코드

패킷의 지속 시간(Duration) 계산

Core Audio에서 사용하는 용어 정의

AudioStreamBasicDescription의 Instance Property

AVAudioPCMBuffer 정리

AVAudioPCMBuffer 정리

목차

AVAudioPCMBuffer 선수 지식 정리

AVAudioPCMBuffer

AVAudioPCMBuffer().frameLength

AVAudioPCMBuffer().frameCapacity

AVAudioPCMBuffer().stride

AVAudioPCMBuffer().floatChannelData

AVAudioPCMBuffer().int16ChannelData, AVAudioPCMBuffer().int32ChannelData

AssetInventory 정리 + AssetInstallationRequest

AssetInventory 정리 + AssetInstallationRequest

목차

Overview

Install assets (에셋 설치하기)

Manage assets (에셋 관리하기)

Downloading and installing assets

AssetInventory.Status