include/vlc/libvlc_media_track.h

   1 /*****************************************************************************
   2  * libvlc_media_track.h:  libvlc external API
   3  *****************************************************************************
   4  * Copyright (C) 1998-2020 VLC authors and VideoLAN
   5  *
   6  * Authors: Clément Stenac <zorglub@videolan.org>
   7  *          Jean-Paul Saman <jpsaman@videolan.org>
   8  *          Pierre d'Herbemont <pdherbemont@videolan.org>
   9  *
  10  * This program is free software; you can redistribute it and/or modify it
  11  * under the terms of the GNU Lesser General Public License as published by
  12  * the Free Software Foundation; either version 2.1 of the License, or
  13  * (at your option) any later version.
  14  *
  15  * This program is distributed in the hope that it will be useful,
  16  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  17  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  18  * GNU Lesser General Public License for more details.
  19  *
  20  * You should have received a copy of the GNU Lesser General Public License
  21  * along with this program; if not, write to the Free Software Foundation,
  22  * Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
  23  *****************************************************************************/
  24
  25 #ifndef VLC_LIBVLC_MEDIA_TRACK_H
  26 #define VLC_LIBVLC_MEDIA_TRACK_H 1
  27
  28 # ifdef __cplusplus
  29 extern "C" {
  30 # else
  31 #  include <stdbool.h>
  32 # endif
  33
  34 /** \defgroup libvlc_media_track LibVLC media track
  35  * \ingroup libvlc
  36  * @ref libvlc_media_track_t is an abstract representation of a media track.
  37  * @{
  38  * \file
  39  * LibVLC media track
  40  */
  41
  42 typedef enum libvlc_track_type_t
  43 {
  44     libvlc_track_unknown   = -1,
  45     libvlc_track_audio     = 0,
  46     libvlc_track_video     = 1,
  47     libvlc_track_text      = 2
  48 } libvlc_track_type_t;
  49
  50 typedef struct libvlc_audio_track_t
  51 {
  52     unsigned    i_channels;
  53     unsigned    i_rate;
  54 } libvlc_audio_track_t;
  55
  56 typedef enum libvlc_video_orient_t
  57 {
  58     libvlc_video_orient_top_left,       /**< Normal. Top line represents top, left column left. */
  59     libvlc_video_orient_top_right,      /**< Flipped horizontally */
  60     libvlc_video_orient_bottom_left,    /**< Flipped vertically */
  61     libvlc_video_orient_bottom_right,   /**< Rotated 180 degrees */
  62     libvlc_video_orient_left_top,       /**< Transposed */
  63     libvlc_video_orient_left_bottom,    /**< Rotated 90 degrees clockwise (or 270 anti-clockwise) */
  64     libvlc_video_orient_right_top,      /**< Rotated 90 degrees anti-clockwise */
  65     libvlc_video_orient_right_bottom    /**< Anti-transposed */
  66 } libvlc_video_orient_t;
  67
  68 typedef enum libvlc_video_projection_t
  69 {
  70     libvlc_video_projection_rectangular,
  71     libvlc_video_projection_equirectangular, /**< 360 spherical */
  72
  73     libvlc_video_projection_cubemap_layout_standard = 0x100,
  74 } libvlc_video_projection_t;
  75
  76 /**
  77  * Viewpoint
  78  *
  79  * \warning allocate using libvlc_video_new_viewpoint()
  80  */
  81 typedef struct libvlc_video_viewpoint_t
  82 {
  83     float f_yaw;           /**< view point yaw in degrees  ]-180;180] */
  84     float f_pitch;         /**< view point pitch in degrees  ]-90;90] */
  85     float f_roll;          /**< view point roll in degrees ]-180;180] */
  86     float f_field_of_view; /**< field of view in degrees ]0;180[ (default 80.)*/
  87 } libvlc_video_viewpoint_t;
  88
  89 typedef enum libvlc_video_multiview_t
  90 {
  91     libvlc_video_multiview_2d,                  /**< No stereoscopy: 2D picture. */
  92     libvlc_video_multiview_stereo_sbs,          /**< Side-by-side */
  93     libvlc_video_multiview_stereo_tb,           /**< Top-bottom */
  94     libvlc_video_multiview_stereo_row,          /**< Row sequential */
  95     libvlc_video_multiview_stereo_col,          /**< Column sequential */
  96     libvlc_video_multiview_stereo_frame,        /**< Frame sequential */
  97     libvlc_video_multiview_stereo_checkerboard, /**< Checkerboard pattern */
  98 } libvlc_video_multiview_t;
  99
 100 typedef struct libvlc_video_track_t
 101 {
 102     unsigned    i_height;
 103     unsigned    i_width;
 104     unsigned    i_sar_num;
 105     unsigned    i_sar_den;
 106     unsigned    i_frame_rate_num;
 107     unsigned    i_frame_rate_den;
 108
 109     libvlc_video_orient_t       i_orientation;
 110     libvlc_video_projection_t   i_projection;
 111     libvlc_video_viewpoint_t    pose; /**< Initial view point */
 112     libvlc_video_multiview_t    i_multiview;
 113 } libvlc_video_track_t;
 114
 115 typedef struct libvlc_subtitle_track_t
 116 {
 117     char *psz_encoding;
 118 } libvlc_subtitle_track_t;
 119
 120 typedef struct libvlc_media_track_t
 121 {
 122     /* Codec fourcc */
 123     uint32_t    i_codec;
 124     uint32_t    i_original_fourcc;
 125     int         i_id; /* DEPRECATED: use psz_id */
 126     libvlc_track_type_t i_type;
 127
 128     /* Codec specific */
 129     int         i_profile;
 130     int         i_level;
 131
 132     union {
 133         libvlc_audio_track_t *audio;
 134         libvlc_video_track_t *video;
 135         libvlc_subtitle_track_t *subtitle;
 136     };
 137
 138     unsigned int i_bitrate;
 139     char *psz_language;
 140     char *psz_description;
 141
 142     /** String identifier of track, can be used to save the track preference
 143      * from an other LibVLC run, only valid when the track is fetch from a
 144      * media_player */
 145     const char *psz_id;
 146     /** A string identifier is stable when it is certified to be the same
 147      * across different playback instances for the same track, only valid when
 148      * the track is fetch from a media_player */
 149     bool id_stable;
 150     /** Name of the track, only valid when the track is fetch from a
 151      * media_player */
 152     char *psz_name;
 153     /** true if the track is selected, only valid when the track is fetch from
 154      * a media_player */
 155     bool selected;
 156
 157 } libvlc_media_track_t;
 158
 159 /**
 160  * Opaque struct containing a list of tracks
 161  */
 162 typedef struct libvlc_media_tracklist_t libvlc_media_tracklist_t;
 163
 164 /**
 165  * Get the number of tracks in a tracklist
 166  *
 167  * \version LibVLC 4.0.0 and later.
 168  *
 169  * \param list valid tracklist
 170  *
 171  * \return number of tracks, or 0 if the list is empty
 172  */
 173 LIBVLC_API size_t
 174 libvlc_media_tracklist_count( const libvlc_media_tracklist_t *list );
 175
 176 /**
 177  * Get a track at a specific index
 178  *
 179  * \warning The behaviour is undefined if the index is not valid.
 180  *
 181  * \version LibVLC 4.0.0 and later.
 182  *
 183  * \param list valid tracklist
 184  * \param index valid index in the range [0; count[
 185  *
 186  * \return a valid track (can't be NULL if libvlc_media_tracklist_count()
 187  * returned a valid count)
 188  */
 189 LIBVLC_API libvlc_media_track_t *
 190 libvlc_media_tracklist_at( libvlc_media_tracklist_t *list, size_t index );
 191
 192 /**
 193  * Release a tracklist
 194  *
 195  * \version LibVLC 4.0.0 and later.
 196  *
 197  * \see libvlc_media_get_tracklist
 198  * \see libvlc_media_player_get_tracklist
 199  *
 200  * \param list valid tracklist
 201  */
 202 LIBVLC_API void
 203 libvlc_media_tracklist_delete( libvlc_media_tracklist_t *list );
 204
 205
 206 /**
 207  * Hold a single track reference
 208  *
 209  * \version LibVLC 4.0.0 and later.
 210  *
 211  * This function can be used to hold a track from a tracklist. In that case,
 212  * the track can outlive its tracklist.
 213  *
 214  * \param track valid track
 215  * \return the same track, need to be released with libvlc_media_track_release()
 216  */
 217 LIBVLC_API libvlc_media_track_t *
 218 libvlc_media_track_hold( libvlc_media_track_t * );
 219
 220 /**
 221  * Release a single track
 222  *
 223  * \version LibVLC 4.0.0 and later.
 224  *
 225  * \warning Tracks from a tracklist are released alongside the list with
 226  * libvlc_media_tracklist_delete().
 227  *
 228  * \note You only need to release tracks previously held with
 229  * libvlc_media_track_hold() or returned by
 230  * libvlc_media_player_get_selected_track() and
 231  * libvlc_media_player_get_track_from_id()
 232  *
 233  * \param track valid track
 234  */
 235 LIBVLC_API void
 236 libvlc_media_track_release( libvlc_media_track_t *track );
 237 /** @}*/
 238
 239 # ifdef __cplusplus
 240 }
 241 # endif
 242
 243 #endif /* VLC_LIBVLC_MEDIA_TRACK_H */