junome
Library Author

XCameraKit

iOS 카메라 기능을 간편하게 구현할 수 있는 Swift 라이브러리

SwiftAVFoundation
Platform
iOS
Framework
AVFoundation
Language
Swift

개요

이 라이브러리는 카메라 코드를 간편하게 활용할 수 있도록 만들어졌습니다. 카메라 기능을 구현하는 과정에서 겪은 어려움을 고려하여, 누구나 쉽게 카메라를 다룰 수 있도록 설계되었습니다. 사용자가 코드를 쉽게 이해하고 활용할 수 있도록 함으로써, 카메라 기능을 간편하게 추가할 수 있도록 돕고자 합니다.

직접 실행해보기

처음에는 카메라 화면을 띄우고 사진 한 장을 찍는 것부터 시작해보면 좋겠습니다. 아래 예제는 촬영한 사진을 화면 오른쪽 위에 보여줍니다. 사진 보관함에 저장하지는 않습니다.

2026년 11월 4일에 확인한 공개 소스 기준으로 적었습니다. 예전 README에 설치 준비 중인 항목들이 남아 있어, 여기서는 Swift Package Manager로 소스 커밋을 지정해 설치합니다. 예제의 대상은 UIKit 앱, iOS 14 이상, Swift 5 모드이며 패키지를 읽으려면 Swift tools 5.9 이상을 지원하는 Xcode가 필요합니다.

1. 패키지 연결하기

  1. Xcode에서 iOS App 프로젝트를 UIKit·Storyboard 방식으로 준비합니다.
  2. File → Add Package Dependencies에서 아래 저장소 URL을 넣고, 버전 번호 대신 아래 커밋을 지정합니다. 앱 타깃에 XCameraKit 제품을 추가해주세요.
https://github.com/jjunhaa0211/XCameraKit

97cc14c0691b843142d285ac70c80c62c5cbafc1

Package.swift에서 의존성을 관리한다면 같은 소스를 아래처럼 지정할 수 있습니다.

.package(
    url: "https://github.com/jjunhaa0211/XCameraKit",
    revision: "97cc14c0691b843142d285ac70c80c62c5cbafc1"
)

이 선언은 dependencies 배열에 넣고, 사용하는 타깃의 의존성에도 .product(name: "XCameraKit", package: "XCameraKit")을 연결합니다. 이 패키지는 UIKit을 사용하므로 macOS 명령줄 프로그램에서는 실행할 수 없습니다.

2. 카메라 권한 설명 넣기

앱 타깃의 Info에서 Privacy - Camera Usage Description(NSCameraUsageDescription)을 추가합니다. Info.plist를 직접 관리한다면 기존 dict 안에 아래 두 줄을 넣어주세요.

<key>NSCameraUsageDescription</key>
<string>사진을 촬영하기 위해 카메라를 사용합니다.</string>

3. ViewController에서 촬영하기

기본 ViewController.swift를 아래 코드로 바꾸고, Storyboard의 시작 화면이 이 클래스를 사용하는지 확인합니다. 실제 iPhone을 실행 대상으로 선택하고 앱을 실행해주세요. 권한을 허용하면 정사각형 미리보기가 나오고, ‘사진 찍기’를 누르면 촬영한 사진이 표시됩니다.

import UIKit
import AVFoundation
import XCameraKit

final class ViewController: UIViewController {
    private var cameraView: XCamera?
    private let sessionQueue = DispatchQueue(label: "camera.session")
    private let captureButton = UIButton(type: .system)
    private let photoView = UIImageView()

    override func viewDidLoad() {
        super.viewDidLoad()
        view.backgroundColor = .black

        photoView.contentMode = .scaleAspectFit
        captureButton.setTitle("사진 찍기", for: .normal)
        captureButton.isEnabled = false
        captureButton.addTarget(self, action: #selector(takePhoto), for: .touchUpInside)

        for control in [photoView, captureButton] {
            control.translatesAutoresizingMaskIntoConstraints = false
            view.addSubview(control)
        }
        NSLayoutConstraint.activate([
            photoView.topAnchor.constraint(equalTo: view.safeAreaLayoutGuide.topAnchor, constant: 16),
            photoView.trailingAnchor.constraint(equalTo: view.trailingAnchor, constant: -16),
            photoView.widthAnchor.constraint(equalToConstant: 100),
            photoView.heightAnchor.constraint(equalToConstant: 100),
            captureButton.centerXAnchor.constraint(equalTo: view.centerXAnchor),
            captureButton.bottomAnchor.constraint(equalTo: view.safeAreaLayoutGuide.bottomAnchor, constant: -24)
        ])
    }

    override func viewDidAppear(_ animated: Bool) {
        super.viewDidAppear(animated)
        switch AVCaptureDevice.authorizationStatus(for: .video) {
        case .authorized:
            showCamera()
        case .notDetermined:
            AVCaptureDevice.requestAccess(for: .video) { [weak self] granted in
                DispatchQueue.main.async {
                    guard let self = self, self.view.window != nil else { return }
                    if granted {
                        self.showCamera()
                    } else {
                        self.showMessage("카메라 접근을 허용해야 촬영할 수 있어요.")
                    }
                }
            }
        case .denied, .restricted:
            showMessage("설정에서 이 앱의 카메라 접근을 확인해주세요.")
        @unknown default:
            showMessage("카메라 권한 상태를 확인할 수 없어요.")
        }
    }

    private func showCamera() {
        guard AVCaptureDevice.default(.builtInWideAngleCamera, for: .video, position: .back) != nil else {
            showMessage("후면 카메라가 있는 실제 iPhone에서 실행해주세요.")
            return
        }
        if cameraView == nil {
            let camera = XCamera(frame: .zero)
            camera.setAspectRatio(.square)
            camera.translatesAutoresizingMaskIntoConstraints = false
            view.insertSubview(camera, at: 0)
            NSLayoutConstraint.activate([
                camera.topAnchor.constraint(equalTo: view.safeAreaLayoutGuide.topAnchor),
                camera.leadingAnchor.constraint(equalTo: view.leadingAnchor),
                camera.trailingAnchor.constraint(equalTo: view.trailingAnchor),
                camera.bottomAnchor.constraint(equalTo: view.safeAreaLayoutGuide.bottomAnchor)
            ])
            cameraView = camera
        }
        guard let camera = cameraView else { return }
        sessionQueue.async { camera.startRunning() }
        captureButton.isEnabled = true
    }

    @objc private func takePhoto() {
        guard let camera = cameraView else { return }
        captureButton.isEnabled = false
        sessionQueue.async {
            camera.capturePhoto { [weak self] result in
                DispatchQueue.main.async {
                    guard let self = self, self.view.window != nil else { return }
                    self.captureButton.isEnabled = true
                    switch result {
                    case .success(let image):
                        self.photoView.image = image
                    case .failure(let error):
                        self.showMessage(error.localizedDescription)
                    }
                }
            }
        }
    }

    override func viewWillDisappear(_ animated: Bool) {
        super.viewWillDisappear(animated)
        captureButton.isEnabled = false
        guard let camera = cameraView else { return }
        sessionQueue.async { camera.stopRunning() }
    }

    private func showMessage(_ message: String) {
        let alert = UIAlertController(title: "카메라", message: message, preferredStyle: .alert)
        alert.addAction(UIAlertAction(title: "확인", style: .default))
        present(alert, animated: true)
    }
}

startRunning()과 stopRunning()은 같은 직렬 큐에서 호출하고, 촬영 결과를 화면에 반영할 때는 메인 큐로 돌아옵니다. 현재 구현은 촬영 완료 콜백을 하나만 보관하므로, 촬영 중에는 버튼을 잠시 꺼서 여러 요청이 겹치지 않게 했습니다.

막히면 여기부터 확인해주세요

  • No such module XCameraKit: 패키지의 제품이 앱 타깃에 추가됐는지, 패키지 확인이 끝났는지 확인합니다. 모듈 이름은 XCameraKit, 뷰 타입은 XCamera입니다.
  • 카메라가 안 보일 때: 실제 기기의 후면 카메라와 앱의 카메라 권한을 확인합니다. 권한을 허용하기 전에 XCamera를 만들지 않도록 순서를 지켜주세요.
  • 사진 보관함에도 저장하고 싶다면: 별도로 저장 코드를 넣고NSPhotoLibraryAddUsageDescription을 설정해야 합니다. 라이브러리의 addTapGesture(allow: true)도 탭 촬영 후 보관함에 저장하는 기능입니다.
  • 플래시와 인쇄: 이 커밋의 setFlashMode는 촬영 시 사용하는 내부 상태를 갱신하지 않고, printImageAsPDF는 외부 앱에서 호출할 수 없는 접근 수준입니다. 위 예제는 기본 플래시 설정으로 촬영하는 범위까지 다룹니다.

회고

XCameraKit를 개발하면서 저는 AVFoundation에 대한 이해도를 한층 더 높일 수 있었습니다. 사용자가 함수의 기능과 파라미터를 보다 쉽게 이해할 수 있도록, 함수에 대한 설명을 추가함으로써 사용자 경험을 개선하고자 했습니다. 더불어, 사용자가 카메라를 보다 유능하게 제어할 수 있도록 다양한 기능을 추가했습니다. 예를 들어, 카메라의 화면 비율을 변경하거나 플래시 모드를 설정할 수 있는 기능, 그리고 핀치 제스처를 사용하여 카메라의 줌 레벨을 조절할 수 있는 기능을 구현했습니다. 이 외에도, 이미지를 PDF로 변환할 수 있는 기능과 에어드랍을 통해 지원하는 인쇄기에 바로 프린트할 수 있는 기능을 추가했습니다. 이 프로젝트를 진행하면서, 남을 생각하며 코드를 구현하는 방법을 배웠으며, 다양한 에러 처리 과정을 경험했습니다.

질문 & 답변

궁금한 점을 남겨주세요 — GitHub 로그인이 필요해요.