src/api/doxy/glossary_termino.dp

   1 /** @page glossary_termino Glossary: Terminology
   2
   3 @section sess_handle libcURL session handle
   4
   5 Calling @ref quvi_new creates a libcURL session handle. This handle is
   6 reused by libquvi to access the Internet until @ref quvi_free is called.
   7 libcURL sets most of the initial values for the handle when it is
   8 created by calling curl_easy_init(3). libquvi will, additionally, make
   9 the following changes to the handle when @ref quvi_new is called:
  10
  11 - CURLOPT_COOKIELIST is set to "ALL" (clear cookies in memory -- *when* @ref
  12   QUVI_OPTION_ALLOW_COOKIES is QUVI_TRUE)
  13 - CURLOPT_COOKIEFILE is set to "" (enable cookies -- *when* @ref
  14   QUVI_OPTION_ALLOW_COOKIES is QUVI_TRUE)
  15 - CURLOPT_HTTPHEADER is set to NULL (clear custom headers)
  16 - CURLOPT_FOLLOWLOCATION is set to 1L (enabled)
  17 - CURLOPT_USERAGENT is set to "Mozilla/5.0"
  18 - CURLOPT_NOBODY is set to 0L (disabled)
  19
  20 The scripts (e.g. @ref m_script) may modify the cookie and HTTP header
  21 settings dynamically which may be required in order to access some of
  22 the resources, e.g. @ref m_stream. For this reason, it may be necessary
  23 for the 3rd party applications using libquvi to reuse the current
  24 session handle in order to access these sources. The session handle may
  25 be queried using the @ref quvi_get function.
  26
  27 The following functions will reset the session handle to its initial
  28 state when they are called:
  29
  30 - @ref quvi_media_new
  31 - @ref quvi_playlist_new
  32 - @ref quvi_scan_new
  33 - @ref quvi_subtitle_new
  34
  35 Any cookie and header settings that were set by any of the scripts
  36 previously, will be lost when those functions are called.
  37
  38 @section media_sect Media
  39
  40 @subsection m_prop Media property
  41
  42 A property that belongs to a medium, e.g. title. These are parsed and
  43 returned by a @ref m_script.
  44
  45 @sa QuviMediaProperty
  46 @sa quvi_get
  47
  48 @subsection m_stream_id Media stream ID
  49
  50 A string value that is used to identify the @ref m_stream. They are
  51 generated for each available media stream. They may vary per website.
  52
  53 The @ref m_stream_id typically consists of:
  54 @li Media container (e.g. "WebM")
  55 @li Media quality (e.g. "hd720")
  56 @li Video encoding (e.g. "VP8")
  57 @li Video height (e.g. "720")
  58
  59 A typical ID could look like:
  60 @verbatim
  61 $quality_$container_$encoding_$height(p)
  62 @endverbatim
  63
  64 Whether they are used in the @ref m_stream_id depends on whether the
  65 website has made the data available, and whether the @ref m_script parses
  66 the properties and uses them.
  67
  68 Sometimes these IDs may as simple as "hd" or "sd", although as of
  69 libquvi(-scripts) 0.9 the media scripts are expected to use the
  70 "standardized representation of the stream ID" whenever possible.
  71
  72 Example: Dailymotion
  73 @verbatim
  74 hq_mp4_h264_480p
  75 @endverbatim
  76
  77 Example: YouTube
  78
  79 Similar, but uses the container value instead of the video
  80 encoding value. It also uses the 'itag' value, which is specific to
  81 YouTube.
  82 @verbatim
  83 hd720_webm_i45_720p
  84 @endverbatim
  85
  86 @sa @ref parse_media
  87
  88 @subsection ms_prop Media stream property
  89
  90 A @ref m_prop that is specific to a @ref m_stream. Like with
  91 @ref m_prop, these are parsed and returned by a @ref m_script.
  92
  93 @sa QuviMediaProperty
  94 @sa quvi_get
  95
  96 @subsection m_stream Media stream
  97
  98 A stream of media, e.g. multimedia. Some websites provide >1 media
  99 streams for the hosted content, in which case the @ref m_script will
 100 usually try to parse the URLs to these streams and return them to the
 101 library.
 102
 103 @sa quvi_media_stream_select
 104 @sa QuviMediaProperty
 105 @sa @ref m_stream_url
 106 @sa quvi_get
 107
 108 @subsection m_stream_best Media stream: Best quality
 109
 110 The best quality stream is determined and flagged as such by
 111 a @ref m_script when there are >1 streams available.
 112 How the best quality stream is determined depends on the website and
 113 the @ref m_script.
 114
 115 The library uses the keyword 'best' with @ref quvi_media_stream_select
 116 to identify this stream.
 117
 118 @sa @ref select_stream
 119
 120 @subsection m_stream_default Media stream: Default quality
 121
 122 This is whatever the @ref m_script returns as the first stream. This
 123 stream is returned always.
 124
 125 @subsection sub_data Subtitle data
 126
 127 The subtitle data format varies per website, e.g. YouTube uses
 128 a custom timed-text (TT) format for CCs and TTSes. Generally speaking,
 129 the applications may ignore this format as the API has been designed
 130 so that the library provides the data in the requested format.
 131
 132 @sa @ref subex_script
 133
 134 @subsection sub_lang Subtitle language
 135
 136 An available subtitle language. Each @ref sub_type consists of
 137 (available) languages.
 138
 139 @sa @ref sub_type
 140
 141 @subsection sub_lang_id Subtitle language ID
 142
 143 A string value that is used to identify the @ref sub_lang. They are
 144 generated for each available language.
 145
 146 @subsection sub_type Subtitle type
 147
 148 Either a closed-caption (CC) or a text-to-speech (TTS, sometimes
 149 referred to as "automatic captions"). Each subtitle consists of a
 150 varying number of available languages.
 151
 152 @sa @ref sub_lang
 153
 154 @subsection m_url Media URL
 155
 156 An Internet address to the media, e.g. "http://youtube.com/watch?v=foo".
 157 This URL should not be confused with @ref m_stream_url.
 158
 159 @note This value is accessible to the scripts as "qargs.input_url"
 160
 161 @subsection m_stream_url Media stream URL
 162
 163 An Internet address to the @ref m_stream.
 164 This URL should not be confused with @ref m_url.
 165
 166 @section plist Playlist
 167
 168 A collection of @ref m_url s.
 169
 170 @section script_property Script property
 171
 172 A property of a script, that may be of either
 173 a @ref m_script, a @ref pl_script, a @ref scan_script or
 174 an @ref u_script.
 175
 176 @sa QuviScriptProperty
 177
 178 @section sh_url Shortened URL
 179
 180 An URL that has been "compressed", or "shortened", by a service such as
 181 is.gd or bit.ly .
 182
 183 @section verification Verification of an URL
 184
 185 A step, previously until libquvi 0.9, was called a "media stream URL
 186 verification process", during which the library would send an HTTP HEAD
 187 request to the server to query the content-type and the content-length.
 188 This step would also try to guess the file extension to the media from
 189 the content-type. This step took place immediately after returning a
 190 @ref m_stream_url from a @ref m_script.
 191
 192 The verification process step was removed in libquvi 0.9, but an
 193 additional function set was added to allow to querying this
 194 meta-info if necessary.
 195
 196 @note Works with HTTP(S) URLs only
 197 @sa http_metainfo
 198 */