PSPDFSoundAnnotation

Objective-C


@interface PSPDFSoundAnnotation : PSPDFAnnotation <PSPDFOverridable>

Swift

class SoundAnnotation : Annotation, Overridable

A sound annotation (PDF 1.2) shall analogous to a text annotation except that instead of a text note, it contains sound recorded from the iOS device’s microphone or imported from a file.

To ensure maximum compatibility set the boundingBox for sound annotations to the same size Adobe Acrobat uses (20x15pt). PSPDFKit will always render sound annotations at a fixed size of 74x44pt, centered in the provided boundingBox.

Note

Make sure you configured Microphone Permissions in your app. See https://pspdfkit.com/guides/ios/current/getting-started/permissions/#toc_microphone-permissions for futher documentation.

Customizing the Appearance

  • The sound icon name.

    Declaration

    Objective-C

    @property (copy, nullable) NSString *iconName;

    Swift

    var iconName: String? { get set }

Determining Capabilities

  • Determines if recording annotations are available.

    Recording sound annotations are not available in all environments. E.g. when running inside an App Extension, sound annotations are unavailable as microphone access is disabled.

    See

    -initWithRecorderOptions:

    Declaration

    Objective-C

    @property (class, nonatomic, readonly) BOOL recordingAnnotationAvailable;

    Swift

    class var recordingAnnotationAvailable: Bool { get }

    Return Value

    true if sound annotations are available, false otherwise.

  • If the annotation is able to record audio

    Declaration

    Objective-C

    @property (readonly) BOOL canRecord;

    Swift

    var canRecord: Bool { get }

Accessing the Audio Metadata

  • The number of bits per sample value per channel. Default value: 16. 8 or 16 bits per channel are supported.

    Declaration

    Objective-C

    @property (readonly) NSUInteger bits;

    Swift

    var bits: UInt { get }

  • The sampling rate, in samples per second.

    Based on the PDF spec, 8000, 11,025, or 22,050 samples per second are most widely supported. Based on empiric testing, 44100 works great as well.

    Declaration

    Objective-C

    @property (readonly) NSUInteger rate;

    Swift

    var rate: UInt { get }

  • The number of sound channels. Default value: 1. The PDF spec supports 1 or 2 channels.

    Declaration

    Objective-C

    @property (readonly) NSUInteger channels;

    Swift

    var channels: UInt { get }

  • Encoding of the sound stream. Use PSPDFSoundAnnotationEncoding* for values.

    Declaration

    Objective-C

    @property (copy, readonly, nullable) PSPDFSoundAnnotationEncoding encoding;

    Swift

    var encoding: SoundAnnotation.Encoding? { get }

Accessing the Audio Data

  • URL to the sound content.

    Declaration

    Objective-C

    @property (copy, readonly, nullable) NSURL *soundURL;

    Swift

    var soundURL: URL? { get }

  • Loads bits, sample rate, channels, encoding from sound file.

    Declaration

    Objective-C

    - (BOOL)loadAttributesFromAudioFile:(NSError *_Nullable *_Nullable)error;

    Swift

    func loadAttributesFromAudioFile() throws

  • Get the direct sound data.

    Declaration

    Objective-C

    @property (readonly, nullable) NSData *soundData;

    Swift

    var soundData: Data? { get }

Creating Instances from a Sound File

  • Initializes a sound annotation with the sound file located at the given URL.

    Use this method if you want to initialize a sound annotation that already has an existing sound file.

    Declaration

    Objective-C

    - (nullable instancetype)initWithURL:(nonnull NSURL *)soundURL
                               error:(NSError *_Nullable *_Nullable)error;

    Swift

    init(url soundURL: URL) throws

    Parameters

    soundURL

    The file URL to the sound file.
    error

    Upon return contains an error if the creation was not possible.

    Return Value

    A new sound annotation, ready to be played.

Creating Instances by Recording a Sound

  • Initializes an empty sound annotation that can be recorded into.

    Pass nil to use the default recording options.

    Warning

    Calling this initializer will throw an exception if +recordingAnnotationAvailable returns false. Check this method before calling -initWithRecorderOptions:.

    See

    +recordingAnnotationAvailable

    Declaration

    Objective-C

    - (nonnull instancetype)initWithRecorderOptions:
    (nullable NSDictionary<NSString *, id> *)recorderOptions;

    Return Value

    A new, empty instance of PSPDFSoundAnnotation.

  • Deprecated

    Deprecated in PSPDFKit 4.2 for macOS. Please use initWithRecorderOptions: with a nil parameter instead.

    Initializes an empty sound annotation that can be recorded into with a default option set.

    Declaration

    Objective-C

    - (nonnull instancetype)initWithRecorder;

Conversions

  • Returns the supported format identifier that corresponds to the given encoding.

    Declaration

    Objective-C

    + (AudioFormatID)audioFormatIDFromEncoding:
    (nullable PSPDFSoundAnnotationEncoding)encoding;

    Swift

    class func audioFormatID(fromEncoding encoding: SoundAnnotation.Encoding?) -> AudioFormatID

  • Customizable audio parameters to use when recording a new sound annotation

    See more

    Declaration

    Swift

    public enum RecorderOption : Hashable
    extension SoundAnnotation.RecorderOption: CustomStringConvertible

  • Create a new sound annotation that can be recorded to, if recording sounds is possible at all.

    This method will fail when recordingAnnotationAvailable is false.

    Declaration

    Swift

    public convenience init?(recorderOptions: Set<RecorderOption> = [])

    Parameters

    recorderOptions

    Customisations for the audio parameters to use when recording.