soundfingerprinting

Since v15.0.0, you can use spectral profiles (SFM + relative power) to bridge regions where hashes don't match, such as broadband noise (ocean waves), fade-outs, or atmospheric silence. This is disabled by default and must be opted into via QueryConfiguration.SfmMatchStrategy during a query.

Available strategies:

• NoBridgingStrategy: Default (no bridging).
• BroadbandNoiseBridgingStrategy: Uses per-second SFM > 0.70 on both sides.
• SilentRegionBridgingStrategy: Uses per-second power < 5% on both sides.
• SimilarProfileBridgingStrategy: Uses tight $|\Delta sfm| < 0.10$ tolerance.
• CompositeBridgingStrategy: A safe union of the above strategies.

Bridging is capped at a 70% cumulative-bridged-seconds limit and is reported via Coverage.BridgedSeconds.

var queryResult = await QueryCommandBuilder.Instance.BuildQueryCommand()
    .From(file)
    .WithQueryConfig(config =>
    {
        // covers both broadband and silent regions in one pass
        config.Audio.SfmMatchStrategy = CompositeBridgingStrategy.BroadbandOrSilent;
        return config;
    })
    .UsingServices(modelService, audioService)
    .Query();

The RealtimeQueryCommand is used to query underlying data storage in real-time by consuming a continuous stream of media. It supports various input sources including broadcast URLs, audio sample streams, file lists, and pre-computed hashes.

To use it, you typically follow a builder-like pattern:

1. Initialize the command (via your command builder).
2. Define the source using .From(...).
3. Provide necessary services (like IQueryService or IMediaService) using .UsingServices(...).
4. Configure the query behavior using .WithRealtimeQueryConfig(...).
5. Execute the query with .Query(CancellationToken).

Note: If querying from a broadcast URL, you must provide an IRealtimeMediaService via .UsingServices(...).

// Example conceptual usage
await realtimeQueryCommand
    .From("http://broadcast-url.com/stream", chunkLength: 1.0, MediaType.Audio)
    .UsingServices(myQueryService, myRealtimeMediaService)
    .WithRealtimeQueryConfig(myConfig)
    .Query(cancellationToken);

To index audio for later recognition, use FingerprintCommandBuilder to generate hashes from a file and then use an IModelService to store them. You will need an IAudioService (such as SoundFingerprintingAudioService) to handle the audio processing.

Example of extracting fingerprints from a file and storing them in an InMemoryModelService:

private readonly IModelService modelService = new InMemoryModelService(); // store fingerprints in RAM
private readonly IAudioService audioService = new SoundFingerprintingAudioService(); // default audio library

public async Task StoreForLaterRetrieval(string file)
{
    var track = new TrackInfo("GBBKS1200164", "Skyfall", "Adele");

    // create fingerprints
    var avHashes = await FingerprintCommandBuilder.Instance
                                .BuildFingerprintCommand()
                                .From(file)
                                .UsingServices(audioService)
                                .Hash();
                                
    // store hashes in the database for later retrieval
    modelService.Insert(track, avHashes);
}

When setting up realtime query operations, you can use the IWithRealtimeQueryConfiguration interface to define how queries are executed. This interface provides two ways to apply configuration:

1. Direct Configuration: Pass a complete RealtimeQueryConfiguration object.
2. Functional Amendment: Pass a Func<RealtimeQueryConfiguration, RealtimeQueryConfiguration> to modify an existing DefaultRealtimeQueryConfiguration instance using an amendment functor.

Both methods return an IInterceptRealtimeSource, allowing for a fluent builder-style configuration pattern.

// Example 1: Using a direct configuration object
services.WithRealtimeQueryConfig(new RealtimeQueryConfiguration { /* settings */ });

// Example 2: Using an amendment functor to modify default settings
services.WithRealtimeQueryConfig(config => {
    config.SomeProperty = true;
    return config;
});

The IUsingQueryServices interface is used to configure the services required for a query command. It allows you to inject the necessary components for accessing fingerprint storage, processing audio/video media, and managing match results.

Depending on whether you are performing audio-only, video-only, or combined audio/video (AV) fingerprinting, you can provide different combinations of services:

• IQueryService: The model service used to access the underlying fingerprint storage.
• IAudioService: Used for building fingerprints from audio sources.
• IVideoService: Used for reading Frames from video sources. Required if you set MediaType.Video on the IQuerySource.
• IMediaService: A versatile service that can read both AudioSamples and Frames to generate AVHashes for querying.
• IAVQueryMatchRegistry: A registry used to store query results in a separate storage.

All UsingServices methods return an IQueryCommand, allowing for a fluent API pattern.

// Example of configuring a query command with a query service and a media service
// that handles both audio and video.
IQueryCommand command = queryCommand
    .UsingServices(queryService, mediaService, queryMatchRegistry);