/** @page select_stream Selecting a media stream 

When the library returns >1 media streams, you can access them using the
@ref quvi_media_stream_next and @ref quvi_media_get as described in
@ref parse_media. Alternatively, the convenience functions
@ref quvi_media_stream_choose_best  and @ref quvi_media_stream_select
could also be used.

@code
quvi_media_t qm = quvi_media_new(q, URL);
abort_if_error();
{
  char *m_url;
  quvi_media_stream_choose_best(qm);
  quvi_media_get(qm, QUVI_MEDIA_STREAM_PROPERTY_URL, &m_url);
}
@endcode

In the above example, we tell the library to choose the stream that was
determined (by the media script) to be of the best quality.

In the example below, we are only interested in a specific
stream with the specified stream ID ("foo"). If it is not found
(matched), the library falls back to the default stream.

@code
quvi_media_t qm = quvi_media_new(q, URL);
abort_if_error();
{
  char *m_url;

  quvi_media_stream_select(qm, "foo");
  abort_if_error(); /* Always check quvi_ok return value with the above. */
  quvi_media_get(qm, QUVI_MEDIA_STREAM_PROPERTY_URL, &m_url);
}
@endcode

Since @ref quvi_media_stream_select takes regular expression patterns,
the following is also possible:

@code
quvi_media_stream_select(qm, "\\w+_\\d+p$");
@endcode

The value may also be a comma-separated list of patterns, e.g.:

@code
quvi_media_stream_select(qm, "foo,bar,baz,croak");
abort_if_error(); /* Always check quvi_ok return value with the above. */
quvi_media_get(qm, QUVI_MEDIA_STREAM_PROPERTY_URL, &m_url);
@endcode

Make a note of the use of the 'croak' keyword. This would cause the
library to return an error if it was reached, e.g. none of the first
three patterns matched any of the available @ref m_stream_id. This
is also the reason why an application should always @ref quvi_ok after
calling @ref quvi_media_stream_select and handle the error, if any.

Refer to the API documentation of @ref quvi_media_stream_select for more
details.

@sa quvi_media_stream_select
@sa @ref m_stream_id
*/