/** @page parse_subtitle Parsing subtitle properties

libquvi provides basic support for parsing subtitle properties and
exporting the available subtitles into a specified format, e.g. SubRip.

@note Not all media have subtitles -- with libquvi the application must
query for the available subtitles per media as shown below

The available @ref sub_script collection determines which websites are
supported by the library. Each script will return all available @ref
sub_type and @ref sub_lang.

@code
quvi_subtitle_t qsub = quvi_subtitle_new(q, URL);
abort_if_error();
{
  quvi_subtitle_type_t qst;

  /* for each subtitle type */
  while (  (qst = quvi_subtitle_type_next(qsub)) != NULL)
    {
      quvi_subtitle_lang_t qsl;
      double d;

      quvi_subtitle_type_get(qst, QUVI_SUBTITLE_TYPE_PROPERTY_TYPE, &d);

      switch (d)
      {
      case QUVI_SUBTITLE_TYPE_TTS:
        puts("type: tts");
        break;
      case QUVI_SUBTITLE_TYPE_CC:
        puts("type: cc");
      default:
        break;
      }

      /* for each subtitle language (of the type). */
      while ( (qsl = quvi_subtitle_lang_next(qst)) != NULL)
        {
          char *s;
          quvi_subtitle_lang_get(qsl, QUVI_SUBTITLE_LANG_PROPERTY_ID, &s);
          puts(s);
        }
    }
}
quvi_subtitle_free(qsub);
@endcode

@sa QuviSubtitleTypeProperty
@sa QuviSubtitleLangProperty

@section sub_select Selecting a language

When the library returns >1 languages, you can access them using the
@ref quvi_subtitle_type_next, @ref quvi_subtitle_lang_next and
@ref quvi_subtitle_lang_get.  Alternatively, the convenience function
@ref quvi_subtitle_select could be used.

The example below asks the library to return the language ID matching
the "cc_en" pattern.

@code
quvi_subtitle_t qsub = quvi_subtitle_new(q, URL);
abort_if_error();
{
  quvi_subtitle_lang_t qsl = quvi_subtitle_select(qsub, "cc_en");
  abort_if_error(); /* Always check quvi_ok return value. */
}
@endcode

Similarly to @ref quvi_media_stream_select, @ref quvi_subtitle_select
takes a comma-separated list of regular expression patterns, so
the following is perfectly OK:

@code
qsl = quvi_subtitle_select(qsub, "tts_e?,cc_a?,croak");
@endcode

If neither "tts_e?" or "cc_a?" matched any of the available subtitles,
the library would exit with an error (croak). By default, the library
will return the default (first available type and the first available
language).

@section sub_export Exporting subtitle languages

libquvi provides basic facility for converting the subtitles from their
internal subtitle format that the website uses to a more standard-like
format, e.g. SubRip, the media players support.

@code
quvi_subtitle_export_t qse = quvi_subtitle_export_new(qsl, "srt");
abort_if_error();
puts(quvi_subtitle_export_data(qse));
quvi_subtitle_export_free(qse);
@endcode

The available @ref subex_script collection determines which export
formats are supported by the library. If your application needs to
know the available export formats, use the @ref script interface for
querying the @ref QUVI_SCRIPT_PROPERTY_EXPORT_FORMAT.

@sa http://en.wikipedia.org/wiki/SubRip#SubRip_text_file_format
@sa @ref acc_script_prop
*/