objc2_shazam_kit/generated/

SHSession.rs

//! This file has been automatically generated by `objc2`'s `header-translator`.
//! DO NOT EDIT
use core::ffi::*;
use core::ptr::NonNull;
use objc2::__framework_prelude::*;
#[cfg(feature = "objc2-avf-audio")]
use objc2_avf_audio::*;
use objc2_foundation::*;

use crate::*;

extern_protocol!(
    /// Methods that the session calls with the result of a match request.
    ///
    /// See also [Apple's documentation](https://developer.apple.com/documentation/shazamkit/shsessiondelegate?language=objc)
    pub unsafe trait SHSessionDelegate: NSObjectProtocol {
        #[cfg(feature = "SHMatch")]
        /// Tells the delegate that the query signature matches an item in the catalog.
        ///
        /// - Parameters:
        /// - session: The session object that performs the match.
        /// - match: The matching items from the catalog.
        #[optional]
        #[unsafe(method(session:didFindMatch:))]
        #[unsafe(method_family = none)]
        unsafe fn session_didFindMatch(&self, session: &SHSession, r#match: &SHMatch);

        #[cfg(feature = "SHSignature")]
        /// Tells the delegate that the query signature doesn't match an item in the catalog, or that there's an error.
        ///
        /// You can retry the match if the error indicates an issue in communicating with the catalog server, such as ``SHError/Code/matchAttemptFailed``.
        ///
        /// - Parameters:
        /// - session: The session object that performs the match.
        /// - signature: The query signature to use for the match.
        /// - error: The error that occurs; otherwise, `nil`, which indicates that there's no match.
        #[optional]
        #[unsafe(method(session:didNotFindMatchForSignature:error:))]
        #[unsafe(method_family = none)]
        unsafe fn session_didNotFindMatchForSignature_error(
            &self,
            session: &SHSession,
            signature: &SHSignature,
            error: Option<&NSError>,
        );
    }
);

extern_class!(
    /// An object that matches a specific audio recording when a segment of that recording is part of captured sound in the Shazam catalog or your custom catalog.
    ///
    /// Prepare to make matches by:
    ///
    /// - Creating a session for the catalog that contains the reference signatures
    /// - Adding your delegate that receives the match results
    ///
    /// Search for a match in one of two ways:
    ///
    /// - Generate a signature for the captured audio and call ``match(_:)``
    /// - Call ``matchStreamingBuffer(_:at:)`` with a streaming audio buffer, and ShazamKit generates the signature for you
    ///
    /// Searching the catalog is asynchronous. The session calls your delegate methods with the result.
    ///
    /// Matching songs in Shazam music requires enabling your app to access the catalog. For more information on enabling your app, see [Enable ShazamKit for an App ID](https://developer.apple.com/help/account/configure-app-services/shazamkit).
    ///
    /// The code below shows searching for a match in the Shazam catalog using an existing audio buffer:
    ///
    /// ```swift
    /// // Set up the session.
    /// let session = SHSession()
    ///
    /// // Create a signature from the captured audio buffer.
    /// let signatureGenerator = SHSignatureGenerator()
    /// try signatureGenerator.append(buffer, at: audioTime)
    /// let signature = signatureGenerator.signature()
    ///
    /// // Check for a match.
    /// let result = await session.result(from: signature)
    ///
    /// // Use the result.
    /// switch result {
    /// case .match(let match):
    /// // Match found.
    /// case .noMatch(let signature):
    /// // No match found.
    /// case .error(let error, let signature):
    /// // An error occurred.
    /// }
    /// ```
    ///
    /// See also [Apple's documentation](https://developer.apple.com/documentation/shazamkit/shsession?language=objc)
    #[unsafe(super(NSObject))]
    #[derive(Debug, PartialEq, Eq, Hash)]
    pub struct SHSession;
);

extern_conformance!(
    unsafe impl NSObjectProtocol for SHSession {}
);

impl SHSession {
    extern_methods!(
        #[cfg(feature = "SHCatalog")]
        /// The catalog object containing the reference signatures and their associated metadata that the session uses to perform matches.
        #[unsafe(method(catalog))]
        #[unsafe(method_family = none)]
        pub unsafe fn catalog(&self) -> Retained<SHCatalog>;

        /// The object that the session calls with the result of a match request.
        #[unsafe(method(delegate))]
        #[unsafe(method_family = none)]
        pub unsafe fn delegate(&self) -> Option<Retained<ProtocolObject<dyn SHSessionDelegate>>>;

        /// Setter for [`delegate`][Self::delegate].
        ///
        /// This is a [weak property][objc2::topics::weak_property].
        #[unsafe(method(setDelegate:))]
        #[unsafe(method_family = none)]
        pub unsafe fn setDelegate(&self, delegate: Option<&ProtocolObject<dyn SHSessionDelegate>>);

        /// Creates a new session object for matching songs in the Shazam Music catalog.
        #[unsafe(method(init))]
        #[unsafe(method_family = init)]
        pub unsafe fn init(this: Allocated<Self>) -> Retained<Self>;

        #[cfg(feature = "SHCatalog")]
        /// Creates a new session object for matching audio in a custom catalog.
        ///
        /// - Parameters:
        /// - catalog: The catalog that contains the reference audio signatures and their associated metadata.
        #[unsafe(method(initWithCatalog:))]
        #[unsafe(method_family = init)]
        pub unsafe fn initWithCatalog(this: Allocated<Self>, catalog: &SHCatalog)
            -> Retained<Self>;

        #[cfg(feature = "objc2-avf-audio")]
        /// Converts the audio in the buffer to a signature, and searches the reference signatures in the session catalog.
        ///
        /// This method continues to generate signatures and perform searches until the audio in the buffer stops, which may result in multiple calls to the ``SHSession/delegate``.
        ///
        /// The audio buffer must be in one of the supported formats. For the list of the supported audio formats, see ``SHSignatureGenerator/append(_:at:)``.
        ///
        /// To use the microphone as input for the buffer, see
        /// <doc
        /// :matching-audio-using-the-built-in-microphone>.
        ///
        /// > Note:
        /// > You must use the audio format of the first call to this method in the current session in all subsequent calls for the session.
        ///
        /// - Parameters:
        /// - buffer: An audio buffer.
        /// - time: The start time of the audio to use for generating the signatures.
        #[unsafe(method(matchStreamingBuffer:atTime:))]
        #[unsafe(method_family = none)]
        pub unsafe fn matchStreamingBuffer_atTime(
            &self,
            buffer: &AVAudioPCMBuffer,
            time: Option<&AVAudioTime>,
        );

        #[cfg(feature = "SHSignature")]
        /// Searches for the query signature in the reference signatures that the session catalog contains.
        ///
        /// - Parameters:
        /// - signature: The signature for searching the catalog of reference signatures.
        #[unsafe(method(matchSignature:))]
        #[unsafe(method_family = none)]
        pub unsafe fn matchSignature(&self, signature: &SHSignature);
    );
}

/// Methods declared on superclass `NSObject`.
impl SHSession {
    extern_methods!(
        #[unsafe(method(new))]
        #[unsafe(method_family = new)]
        pub unsafe fn new() -> Retained<Self>;
    );
}