resolveStreamsByPredicate static method

Future<List<LSLStreamInfo>> resolveStreamsByPredicate({ required String predicate, double waitTime = 5.0, int minStreamCount = 0, int maxStreams = 5, })

Discovers LSL streams using XPath 1.0 predicate expressions.

This method provides powerful filtering capabilities using XPath predicates, allowing complex queries involving multiple criteria, text functions, and metadata inspection.

Parameters:

• predicate: XPath 1.0 predicate expression (see examples below)
• waitTime: Maximum wait time in seconds (default: 5.0)
• minStreamCount: Minimum streams to find before returning (default: 0)
• maxStreams: Maximum streams to return (default: 5)

Available XPath Functions:

• starts-with(field, text): Check if field starts with text
• contains(field, text): Check if field contains text
• count(path): Count matching elements in metadata
• Standard comparison operators: =, !=, <, <=, >, >=
• Logical operators: and, or, not()

Queryable Fields:

• name: Stream name
• type: Content type
• channel_count: Number of channels
• nominal_srate: Sample rate
• source_id: Source identifier
• //info/desc/...: Metadata elements in description

Usage Examples:

// Basic property matching
final streams = await LSL.resolveStreamsByPredicate(
  predicate: "name='EEG_Stream' and type='EEG'",
);

// Text functions
final bioStreams = await LSL.resolveStreamsByPredicate(
  predicate: "starts-with(name, 'BioSemi') or contains(name, 'EEG')",
);

// Numeric comparisons
final highSampleRate = await LSL.resolveStreamsByPredicate(
  predicate: "nominal_srate >= 1000 and channel_count = 32",
);

// Metadata queries
final withChannels = await LSL.resolveStreamsByPredicate(
  predicate: "count(//info/desc/channels/channel) > 0",
);

Returns: List of LSLStreamInfo objects matching the predicate

Error Handling: Invalid XPath expressions return empty results rather than throwing exceptions.

See Also:

• XPath 1.0 Specification
• resolveStreamsByProperty for simple property filtering
• resolveStreams for discovering all streams

Implementation

static Future<List<LSLStreamInfo>> resolveStreamsByPredicate({
  required String predicate,
  double waitTime = 5.0,
  int minStreamCount = 0,
  int maxStreams = 5,
}) async {
  final resolver = createResolver(maxStreams: maxStreams);
  final streams = await resolver.resolveByPredicate(
    predicate: predicate,
    waitTime: waitTime,
    minStreamCount: minStreamCount,
  );
  // free the resolver
  resolver.destroy();
  // these stream info pointers remain until they are destroyed
  return streams;
}