Repository navigation
Interpreting query results
Sergiu Ciumac edited this page Oct 15, 2026
·
2 revisions
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.
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 fromAudioSamples.RelativeToandQueryMatchStartsAt. Useful for realtime queries.
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- gapxis shorter than the permitted gap, so it counts as matched; gapyis 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, gapy. -
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;0unlessSfmMatchStrategyis set. -
TrackGaps- will contain one entry ofGapclass withStart= 10,End= 15.