Update 2023-08-20, specific to this fork
- Other forks existing as of this date have been examined for changes from the upstream repository. Changes that appear useful to everyone (not just specific projects or organizations) have been merged into this fork.
- The
developbranch has been merged intomasterand deleted. All new changes from this point should start frommasterand plan to pull-request back intomaster. - The
masterbranch will eventually get renamed tomain, but other work needs to get done first. In particular, the CocoaPodsrakefileneeds to get updated.
Original README from the upstream repository:
This library is no longer actively maintained. If you are interested in maintaining it, please contact the original author.
A lightweight, easy-to-use barcode scanning library for iOS 8+. This library is built on top of Apple's excellent AVFoundation framework, and will continue to receive updates as Apple releases them.
With this library you can:
- Supply a custom UIView for displaying camera input
- Read any number of barcodes before stopping
- Read multiple codes on the screen at the same time (2D barcodes only)
- Easily read codes with a block, including the string value and position in the preview
- Easily flip from the back to the front camera
- Toggle the device's torch on and off
- Freeze and unfreeze capture to display a still image from the camera
See demo project for examples of capturing one code, multiple codes, or highlighting codes as valid or invalid in the live preview.
MTBBarcodeScanner can be installed via CocoaPods by adding the following line to your Podfile:
pod "MTBBarcodeScanner"
Carthage is a decentralized dependency manager that builds your dependencies and provides you with binary frameworks.
You can install Carthage with Homebrew using the following command:
$ brew update
$ brew install carthageTo integrate MTBBarcodeScanner into your Xcode project using Carthage, specify it in your Cartfile:
github "mikebuss/MTBBarcodeScanner"
Run carthage update to build the framework and drag the built MTBBarcodeScanner.framework into your Xcode project.
If you'd prefer not to use a dependency manager, you can download these two files and add them to your project:
To import the library: #import "MTBBarcodeScanner.h"
To initialize an instance of MTBBarcodeScanner:
scanner = [[MTBBarcodeScanner alloc] initWithPreviewView:self.previewView];Where previewView is the UIView in which the camera input will be displayed.
If you only want to scan for certain MetaObjectTypes, you can initialize with the initWithMetadataObjectTypes:previewView: method:
s = [[MTBBarcodeScanner alloc] initWithMetadataObjectTypes:@[AVMetadataObjectTypeQRCode]
previewView:self.previewView];If you are using the MTBBarcodeScanner library on iOS 10 and later, you need to include the following Info.plist key in order to request camera access or the application will crash:
<key>NSCameraUsageDescription</key>
<string>Can we access your camera in order to scan barcodes?</string>Of course you can also set your own (localized) message here. To find out more about privacy-keys in iOS, check the official Apple documentation.
To read the first code and stop scanning:
Note: To avoid a delay in the camera feed, start scanning in viewDidAppear and not viewDidLoad.
[MTBBarcodeScanner requestCameraPermissionWithSuccess:^(BOOL success) {
if (success) {
NSError *error = nil;
[self.scanner startScanningWithResultBlock:^(NSArray *codes) {
AVMetadataMachineReadableCodeObject *code = [codes firstObject];
NSLog(@"Found code: %@", code.stringValue);
[self.scanner stopScanning];
} error:&error];
} else {
// The user denied access to the camera
}
}];If the camera is pointed at more than one 2-dimensional code, you can read all of them:
NSError *error = nil;
[self.scanner startScanningWithResultBlock:^(NSArray *codes) {
for (AVMetadataMachineReadableCodeObject *code in codes) {
NSLog(@"Found code: %@", code.stringValue);
}
[self.scanner stopScanning];
} error:&error];Note: This only applies to 2-dimensional barcodes as 1-dimensional barcodes can only be read one at a time. See relevant Apple document.
To continuously read and only output unique codes:
NSError *error = nil;
[self.scanner startScanningWithResultBlock:^(NSArray *codes) {
for (AVMetadataMachineReadableCodeObject *code in codes) {
if ([self.uniqueCodes indexOfObject:code.stringValue] == NSNotFound) {
[self.uniqueCodes addObject:code.stringValue];
NSLog(@"Found unique code: %@", code.stringValue);
}
}
} error:&error];An alternative way to setup MTBBarcodeScanner is to configure the blocks directly, like so:
self.scanner.didStartScanningBlock = ^{
NSLog(@"The scanner started scanning! We can now hide any activity spinners.");
};
self.scanner.resultBlock = ^(NSArray *codes){
NSLog(@"Found these codes: %@", codes);
};
self.scanner.didTapToFocusBlock = ^(CGPoint point){
NSLog(@"The user tapped the screen to focus. \
Here we could present a view at %@", NSStringFromCGPoint(point));
};
[self.scanner startScanning];This is useful if you would like to present a spinner while MTBBarcodeScanner is initializing.
If you would like to reference self in one of these blocks, remember to use a weak reference to avoid a retain cycle:
__weak MyViewController *weakSelf = self;
self.scanner.resultBlock = ^(NSArray *codes){
[weakSelf drawOverlaysOnCodes:codes];
};See the SwiftExampleViewController.swift file in the repository for a working example of this.
import UIKit
import MTBBarcodeScanner
class SwiftExampleViewController: UIViewController {
@IBOutlet var previewView: UIView!
var scanner: MTBBarcodeScanner?
override func viewDidLoad() {
super.viewDidLoad()
scanner = MTBBarcodeScanner(previewView: previewView)
// Alternatively, limit the type of codes you can scan:
// scanner = MTBBarcodeScanner(metadataObjectTypes: [AVMetadataObject.ObjectType.qr.rawValue], previewView: previewView)
}
override func viewDidAppear(_ animated: Bool) {
super.viewDidAppear(animated)
MTBBarcodeScanner.requestCameraPermission(success: { success in
if success {
do {
try self.scanner?.startScanning(resultBlock: { codes in
if let codes = codes {
for code in codes {
let stringValue = code.stringValue!
print("Found code: \(stringValue)")
}
}
})
} catch {
NSLog("Unable to start scanning")
}
} else {
UIAlertView(title: "Scanning Unavailable", message: "This app does not have permission to access the camera", delegate: nil, cancelButtonTitle: nil, otherButtonTitles: "Ok").show()
}
})
}
override func viewWillDisappear(_ animated: Bool) {
self.scanner?.stopScanning()
super.viewWillDisappear(animated)
}
}To start scanning with a particular camera (front or back):
try self.scanner?.startScanning(with: .front,
resultBlock: { codes in
if let codes = codes {
for code in codes {
let stringValue = code.stringValue!
print("Found code: \(stringValue)")
}
}import UIKit
import MTBBarcodeScanner
class ViewController: UIViewController {
var scanner: MTBBarcodeScanner?
override func viewDidLoad() {
super.viewDidLoad()
scanner = MTBBarcodeScanner(previewView: self.view)
}
override func viewDidAppear(animated: Bool) {
super.viewDidAppear(animated)
scanner?.startScanningWithResultBlock({ (codes) in
for code in codes {
print(code)
}
}, error: nil)
}
}By default, MTBBarcodeScanner will allow the user to tap the screen to focus the camera. To disable this functionality, set the allowTapToFocus property to NO. To be notified when the user taps the screen, provide a block for the didTapToFocusBlock property, like so:
self.scanner.didTapToFocusBlock = ^(CGPoint point){
NSLog(@"The user tapped the screen to focus. \
Here we could present a view at %@", NSStringFromCGPoint(point));
};Switch to the opposite camera with the flipCamera method on the scanner:
- (IBAction)switchCameraTapped:(id)sender {
[self.scanner flipCamera];
}
Or specify the camera directly using setCamera:error, like so:
NSError *error = nil;
MTBBarcodeScanner *scanner = [[MTBBarcodeScanner alloc] initWithPreviewView:_previewView];
[scanner setCamera:MTBCameraFront error:&error];
Examples for these are in the demo project.
Under some circumstances you may want to freeze the video feed when capturing barcodes. To do this, call the freezeCapture and unfreezeCapture methods.
To limit the section of the screen that barcodes can be scanned in, set the scanRect property on MTBBarcodeScanner inside the didStartScanning callback block. See MTBAdvancedExampleViewController for a working example of this.
__weak MTBAdvancedExampleViewController *weakSelf = self;
self.scanner.didStartScanningBlock = ^{
weakSelf.scanner.scanRect = weakSelf.viewOfInterest.frame;
};
To control the torch, set the torchMode property or call the toggleTorch method.
Available values include:
MTBTorchModeOff,
MTBTorchModeOn,
MTBTorchModeAutoTo capture a still image, call the captureStillImage: method after you've started scanning.
The primary goals of this library are to:
- Provide an easy-to-use interface for barcode scanning
- Make as few assumptions about the scanning process as possible
- Don't assume the user wants to scan one code at a time
- Don't assume the camera input view should be a particular size
- Don't assume the scanning process will have it's own view controller
Mike Buss
MTBBarcodeScanner is available under the MIT license. See the LICENSE file for more info.