Skip to content

Interpreting query results

Sergiu Ciumac edited this page Oct 15, 2026 · 2 revisions

Query results

After you've issued a query, an AVQueryResult object is returned from the QueryCommand. The object will contain separate Audio and Video properties of QueryResult type. You can deconstruct it the following way:

public async Task Query(string path)
{
    var (audio, video) = await QueryCommandBuilder.Instance
        .BuildQueryCommand()
        .From(path, MediaType.Audio | MediaType.Video)
        .UsingServices(modelService, mediaService)
        .Query();

    OutputMatches(audio?.ResultEntries, MediaType.Audio);
    OutputMatches(video?.ResultEntries, MediaType.Video);
}

public void OutputMatches(IEnumerable<ResultEntry>? results, MediaType mediaType)
{
    foreach (var resultEntry in results ?? Enumerable.Empty<ResultEntry>())
    {
        if (resultEntry.Confidence > 0.15)
        {
            Console.WriteLine($"Matched ${resultEntry.Track.Id} on media type {mediaType} query, confidence {resultEntry.Confidence:0.00}.");
            Console.WriteLine($"Relative track coverage {resultEntry.TrackRelativeCoverage:0.00}");
            Console.WriteLine($"Relative query coverage {resultEntry.QueryRelativeCoverage:0.00}");
            OutputCoverage(resultEntry.Coverage);
            Console.WriteLine("\n");
        }
    } 
}

private void OutputCoverage(Coverage coverage)
{
    Console.WriteLine($"Track discrete coverage length {coverage.TrackDiscreteCoverageLength}, with detected {coverage.TrackGaps.Count()} gaps of length {coverage.TrackGapsCoverageLength}");
    Console.WriteLine($"Query discrete coverage length {coverage.QueryDiscreteCoverageLength}, with detected {coverage.QueryGaps.Count()} gaps");
}

The QueryResult object will contain aggregated result entries (i.e., instances of ResultEntry class), each one corresponding to a different matched track.

Query result details

Every ResultEntry object will contain the following information:

  • Track - the matched track from the datastore.
  • Coverage - the full description of how the query and the track overlap, see below.
  • TrackCoverageWithPermittedGapsLength - how many seconds of the track matched, counting gaps shorter than the permitted gap as matched.
  • DiscreteTrackCoverageLength - the distance in seconds from the first to the last matched position in the track, gaps included.
  • QueryMatchStartsAt - the position in the query where the track started to match.
  • TrackMatchStartsAt - the position in the track where the query started to match.
  • TrackStartsAt - where the track would start relative to the query (QueryMatchStartsAt - TrackMatchStartsAt); negative when the query begins inside the track.
  • QueryLength - the length of the query in seconds.
  • Confidence - a value in [0, 1]. Below 0.15 is most probably a false positive; above 0.15 is very likely an exact match. Good quality queries reach a confidence above 0.5.
  • Score - the similarity count (hash votes) between the query match and the track; useful to rank candidates of the same query, not comparable across queries of different lengths.
  • MatchedAt - the timestamp at which the match occurred, derived from AudioSamples.RelativeTo and QueryMatchStartsAt. Useful for realtime queries.

Coverage object describing all the details about the match

As an example think about Track A matched with the query in the following regions (a, b and c):

Track A        -------------------------------------------
                  a          b                   c
                        x             y
Matched        -------     ------           --------------
Time (sec)     0     5     7   10           15          30

Permitted gap is a query configuration parameter (QueryConfiguration.PermittedGap, default 2 seconds); the example below uses 2.5.

  • TrackCoverageWithPermittedGapsLength = a + x + b + c = 5 + 2 + 3 + 15 = 25 - gap x is shorter than the permitted gap, so it counts as matched; gap y is not.
  • TrackDiscreteCoverageLength = a + x + b + y + c = 5 + 2 + 3 + 5 + 15 = 30 - first to last matched position.
  • TrackGapsCoverageLength = 5 - the seconds inside the match that are not covered, gap y.
  • TrackRelativeCoverage = TrackCoverageWithPermittedGapsLength / TrackLength - the share of the track that matched.
  • TrackMatchStartsAt = 0, TrackMatchEndsAt = 30 - the matched region of the track.
  • The query side has the same set: QueryCoverageWithPermittedGapsLength, QueryDiscreteCoverageLength, QueryGapsCoverageLength, QueryRelativeCoverage, QueryMatchStartsAt, QueryMatchEndsAt, QueryGaps.
  • BestPath - the matched points themselves (MatchedWith: query position, track position, score), the raw data every value above is derived from.
  • BridgedSeconds - seconds of the match reconstructed by spectral-profile bridging rather than hash matches; 0 unless SfmMatchStrategy is set.
  • TrackGaps - will contain one entry of Gap class with Start = 10, End = 15.

Clone this wiki locally