live
OggFile.hh
Go to the documentation of this file.
1 /**********
2 This library is free software; you can redistribute it and/or modify it under
3 the terms of the GNU Lesser General Public License as published by the
4 Free Software Foundation; either version 3 of the License, or (at your
5 option) any later version. (See <http://www.gnu.org/copyleft/lesser.html>.)
6 
7 This library is distributed in the hope that it will be useful, but WITHOUT
8 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
9 FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for
10 more details.
11 
12 You should have received a copy of the GNU Lesser General Public License
13 along with this library; if not, write to the Free Software Foundation, Inc.,
14 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
15 **********/
16 // "liveMedia"
17 // Copyright (c) 1996-2021 Live Networks, Inc. All rights reserved.
18 // A class that encapsulates an Ogg file
19 // C++ header
20 
21 #ifndef _OGG_FILE_HH
22 #define _OGG_FILE_HH
23 
24 #ifndef _RTP_SINK_HH
25 #include "RTPSink.hh"
26 #endif
27 #ifndef _HASH_TABLE_HH
28 #include "HashTable.hh"
29 #endif
30 
31 class OggTrack; // forward
32 class OggDemux; // forward
33 
34 typedef void OggDemuxOnDeletionFunc(void* objectToNotify, OggDemux* demuxBeingDeleted);
35 
36 class OggFile: public Medium {
37 public:
38  typedef void (onCreationFunc)(OggFile* newFile, void* clientData);
39  static void createNew(UsageEnvironment& env, char const* fileName,
40  onCreationFunc* onCreation, void* onCreationClientData);
41  // Note: Unlike most "createNew()" functions, this one doesn't return a new object
42  // immediately. Instead, because this class requires file reading (to parse the
43  // Ogg track headers) before a new object can be initialized, the creation of a new object
44  // is signalled by calling - from the event loop - an 'onCreationFunc' that is passed as
45  // a parameter to "createNew()".
46 
47  OggTrack* lookup(u_int32_t trackNumber);
48 
49  OggDemux* newDemux(OggDemuxOnDeletionFunc* onDeletionFunc = NULL, void* objectToNotify = NULL);
50  // Creates a demultiplexor for extracting tracks from this file.
51  // (Separate clients will typically have separate demultiplexors.)
52 
53  char const* fileName() const { return fFileName; }
54  unsigned numTracks() const;
55 
57  createSourceForStreaming(FramedSource* baseSource, u_int32_t trackNumber,
58  unsigned& estBitrate, unsigned& numFiltersInFrontOfTrack);
59  // Takes a data source (which must be a demultiplexed track from this file) and returns
60  // a (possibly modified) data source that can be used for streaming.
61 
62  RTPSink* createRTPSinkForTrackNumber(u_int32_t trackNumber, Groupsock* rtpGroupsock,
63  unsigned char rtpPayloadTypeIfDynamic);
64  // Creates a "RTPSink" object that would be appropriate for streaming the specified track,
65  // or NULL if no appropriate "RTPSink" exists
66 
67  class OggTrackTable& trackTable() { return *fTrackTable; }
68 
69 private:
70  OggFile(UsageEnvironment& env, char const* fileName, onCreationFunc* onCreation, void* onCreationClientData);
71  // called only by createNew()
72  virtual ~OggFile();
73 
74  static void handleEndOfBosPageParsing(void* clientData);
76 
77  void addTrack(OggTrack* newTrack);
78  void removeDemux(OggDemux* demux);
79 
80 private:
81  friend class OggFileParser;
82  friend class OggDemux;
83  char const* fFileName;
86 
87  class OggTrackTable* fTrackTable;
90 };
91 
92 class OggTrack {
93 public:
95  virtual ~OggTrack();
96 
97  // track parameters
98  u_int32_t trackNumber; // bitstream serial number
99  char const* mimeType; // NULL if not known
100 
101  unsigned samplingFrequency, numChannels; // for audio tracks
102  unsigned estBitrate; // estimate, in kbps (for RTCP)
103 
104  // Special headers for Vorbis audio, Theora video, and Opus audio tracks:
105  struct _vtoHdrs {
106  u_int8_t* header[3]; // "identification", "comment", "setup"
107  unsigned headerSize[3];
108 
109  // Fields specific to Vorbis audio:
110  unsigned blocksize[2]; // samples per frame (packet)
111  unsigned uSecsPerPacket[2]; // computed as (blocksize[i]*1000000)/samplingFrequency
115  // an array (of size "vorbis_mode_count") of indexes into the (2-entry) "blocksize" array
116 
117  // Fields specific to Theora video:
118  u_int8_t KFGSHIFT;
119  unsigned uSecsPerFrame;
120 
122 
124  return
125  vtoHdrs.header[0] == NULL ||
126  vtoHdrs.header[1] == NULL ||
127  (vtoHdrs.header[2] == NULL && strcmp(mimeType, "audio/OPUS") != 0);
128  }
129 };
130 
132 public:
133  OggTrackTableIterator(class OggTrackTable& ourTable);
135 
137 
138 private:
140 };
141 
142 class OggDemux: public Medium {
143 public:
144  FramedSource* newDemuxedTrack(u_int32_t& resultTrackNumber);
145  // Returns a new stream ("FramedSource" subclass) that represents the next media track
146  // from the file. This function returns NULL when no more media tracks exist.
147 
149  // As above, but creates a new stream for a specific track number within the Matroska file.
150  // (You should not call this function more than once with the same track number.)
151 
152  // Note: We assume that:
153  // - Every track created by "newDemuxedTrack()" is later read
154  // - All calls to "newDemuxedTrack()" are made before any track is read
155 
156 protected:
157  friend class OggFile;
158  friend class OggFileParser;
159  class OggDemuxedTrack* lookupDemuxedTrack(u_int32_t trackNumber);
160 
161  OggDemux(OggFile& ourFile);
162  virtual ~OggDemux();
163 
164 private:
165  friend class OggDemuxedTrack;
166  void removeTrack(u_int32_t trackNumber);
167  void continueReading(); // called by a demuxed track to tell us that it has a pending read ("doGetNextFrame()")
168 
169  static void handleEndOfFile(void* clientData);
171 
172 private:
177 };
178 
179 #endif
unsigned char Boolean
Definition: Boolean.hh:25
void OggDemuxOnDeletionFunc(void *objectToNotify, OggDemux *demuxBeingDeleted)
Definition: OggFile.hh:34
#define NULL
Definition: Media.hh:50
void continueReading()
class OggDemuxedTrack * lookupDemuxedTrack(u_int32_t trackNumber)
virtual ~OggDemux()
HashTable * fDemuxedTracksTable
Definition: OggFile.hh:175
OggTrackTableIterator * fIter
Definition: OggFile.hh:176
class OggFileParser * fOurParser
Definition: OggFile.hh:174
void handleEndOfFile()
FramedSource * newDemuxedTrackByTrackNumber(unsigned trackNumber)
static void handleEndOfFile(void *clientData)
FramedSource * newDemuxedTrack(u_int32_t &resultTrackNumber)
OggDemux(OggFile &ourFile)
OggFile & fOurFile
Definition: OggFile.hh:173
void removeTrack(u_int32_t trackNumber)
void * fOnCreationClientData
Definition: OggFile.hh:85
void removeDemux(OggDemux *demux)
virtual ~OggFile()
OggDemux * newDemux(OggDemuxOnDeletionFunc *onDeletionFunc=NULL, void *objectToNotify=NULL)
class OggTrackTable & trackTable()
Definition: OggFile.hh:67
HashTable * fDemuxesTable
Definition: OggFile.hh:88
onCreationFunc * fOnCreation
Definition: OggFile.hh:84
class OggTrackTable * fTrackTable
Definition: OggFile.hh:87
void() onCreationFunc(OggFile *newFile, void *clientData)
Definition: OggFile.hh:38
char const * fFileName
Definition: OggFile.hh:83
static void handleEndOfBosPageParsing(void *clientData)
void handleEndOfBosPageParsing()
FramedSource * createSourceForStreaming(FramedSource *baseSource, u_int32_t trackNumber, unsigned &estBitrate, unsigned &numFiltersInFrontOfTrack)
char const * fileName() const
Definition: OggFile.hh:53
unsigned numTracks() const
OggTrack * lookup(u_int32_t trackNumber)
static void createNew(UsageEnvironment &env, char const *fileName, onCreationFunc *onCreation, void *onCreationClientData)
class OggFileParser * fParserForInitialization
Definition: OggFile.hh:89
void addTrack(OggTrack *newTrack)
RTPSink * createRTPSinkForTrackNumber(u_int32_t trackNumber, Groupsock *rtpGroupsock, unsigned char rtpPayloadTypeIfDynamic)
OggFile(UsageEnvironment &env, char const *fileName, onCreationFunc *onCreation, void *onCreationClientData)
OggTrackTableIterator(class OggTrackTable &ourTable)
HashTable::Iterator * fIter
Definition: OggFile.hh:139
virtual ~OggTrackTableIterator()
u_int32_t trackNumber
Definition: OggFile.hh:98
unsigned samplingFrequency
Definition: OggFile.hh:101
Boolean weNeedHeaders() const
Definition: OggFile.hh:123
unsigned numChannels
Definition: OggFile.hh:101
char const * mimeType
Definition: OggFile.hh:99
struct OggTrack::_vtoHdrs vtoHdrs
virtual ~OggTrack()
unsigned estBitrate
Definition: OggFile.hh:102
unsigned headerSize[3]
Definition: OggFile.hh:107
unsigned blocksize[2]
Definition: OggFile.hh:110
unsigned uSecsPerFrame
Definition: OggFile.hh:119
unsigned vorbis_mode_count
Definition: OggFile.hh:112
u_int8_t * vorbis_mode_blockflag
Definition: OggFile.hh:114
unsigned ilog_vorbis_mode_count_minus_1
Definition: OggFile.hh:113
u_int8_t * header[3]
Definition: OggFile.hh:106
u_int8_t KFGSHIFT
Definition: OggFile.hh:118
unsigned uSecsPerPacket[2]
Definition: OggFile.hh:111