Audacity  3.0.3
ImportPlugin.h
Go to the documentation of this file.
1 /**********************************************************************
2 
3  Audacity: A Digital Audio Editor
4 
5  ImportPlugin.h
6 
7  Joshua Haberman
8  Leland Lucius
9 
10 *******************************************************************//****************************************************************//****************************************************************//****************************************************************//*******************************************************************/
44 
45 #ifndef __AUDACITY_IMPORTER__
46 #define __AUDACITY_IMPORTER__
47 
48 
49 
50 #include <memory>
51 #include "audacity/Types.h"
52 #include "Identifier.h"
53 #include "Internat.h"
54 #include "SampleFormat.h"
55 #include "wxArrayStringEx.h"
56 
57 class AudacityProject;
58 class ProgressDialog;
59 namespace BasicUI{ enum class ProgressResult : unsigned; }
60 class WaveTrackFactory;
61 class Track;
62 class Tags;
63 
64 class ImportFileHandle;
65 
66 class AUDACITY_DLL_API ImportPlugin /* not final */
67 {
68 public:
69 
70  // Get unique string ID of this plugin, usually it corresponds
71  // to the underlying library, i.e. "libsndfile", "libflac", "libav"
72  // These MUST NOT change across Audacity versions (but NEW IDs can
73  // be added).
74  virtual wxString GetPluginStringID() = 0;
75 
76  // Get a description of the file type this importer can import.
77  // Examples: "Ogg Vorbis", "MP3", "Uncompressed PCM"
79 
80  // Get a list of extensions this plugin expects to be able to
81  // import. If a filename matches any of these extensions,
82  // this importer will get first dibs on importing it.
83  virtual FileExtensions GetSupportedExtensions();
84 
85  bool SupportsExtension(const FileExtension &extension);
86 
87  // Open the given file, returning true if it is in a recognized
88  // format, false otherwise. This puts the importer into the open
89  // state.
90  virtual std::unique_ptr<ImportFileHandle> Open(
91  const FilePath &Filename, AudacityProject*) = 0;
92 
93  virtual ~ImportPlugin();
94 
95 protected:
96 
97  ImportPlugin(FileExtensions supportedExtensions);
98 
100 };
101 
102 
103 class WaveTrack;
104 using TrackHolders = std::vector< std::vector< std::shared_ptr<WaveTrack> > >;
105 
106 class AUDACITY_DLL_API ImportFileHandle /* not final */
107 {
108 public:
110 
111  ImportFileHandle(const FilePath & filename);
112 
113  virtual ~ImportFileHandle();
114 
115  // The importer should call this to create the progress dialog and
116  // identify the filename being imported.
117  void CreateProgress();
118 
119  // This is similar to GetPluginFormatDescription, but if possible the
120  // importer will return a more specific description of the
121  // specific file that is open.
123 
124  // Return an estimate of how many bytes the file will occupy once
125  // imported. In principle this may exceed main memory, so don't use
126  // size_t.
127  using ByteCount = unsigned long long;
129 
130  // do the actual import, creating whatever tracks are necessary with
131  // the WaveTrackFactory and calling the progress callback every iteration
132  // through the importing loop
133  // The given Tags structure may also be modified.
134  // In case of errors or exceptions, it is not necessary to leave outTracks
135  // or tags unmodified.
136  // If resulting outTracks is not empty,
137  // then each member of it must be a nonempty vector.
138  virtual ProgressResult Import(WaveTrackFactory *trackFactory, TrackHolders &outTracks,
139  Tags *tags) = 0;
140 
141  // Return number of elements in stream list
142  virtual wxInt32 GetStreamCount() = 0;
143 
144  // Return stream descriptions list
145  virtual const TranslatableStrings &GetStreamInfo() = 0;
146 
147  // Set stream "import/don't import" flag
148  virtual void SetStreamUsage(wxInt32 StreamID, bool Use) = 0;
149 
151  static sampleFormat ChooseFormat(sampleFormat effectiveFormat);
152 
154  std::shared_ptr<WaveTrack> NewWaveTrack( WaveTrackFactory &trackFactory,
155  sampleFormat effectiveFormat, double rate);
156 
157 protected:
159  std::unique_ptr<ProgressDialog> mProgress;
160 };
161 
162 
163 
165 {
166 public:
168  const TranslatableString &formatName, FileExtensions extensions):
169  mFormatName(formatName),
170  mExtensions( std::move( extensions ) )
171  {
172  }
173 
175  {
176  return mFormatName;
177  }
178 
179  bool SupportsExtension(const FileExtension &extension)
180  {
181  return mExtensions.Index(extension, false) != wxNOT_FOUND;
182  }
183 
184 private:
187 };
188 
189 #endif
TranslatableString
Holds a msgid for the translation catalog; may also bind format arguments.
Definition: TranslatableString.h:32
WaveTrack
A Track that contains audio waveform data.
Definition: WaveTrack.h:69
ImportPlugin::GetPluginFormatDescription
virtual TranslatableString GetPluginFormatDescription()=0
TrackHolders
std::vector< std::vector< std::shared_ptr< WaveTrack > > > TrackHolders
Definition: Import.h:39
UnusableImportPlugin::UnusableImportPlugin
UnusableImportPlugin(const TranslatableString &formatName, FileExtensions extensions)
Definition: ImportPlugin.h:167
TranslatableStrings
std::vector< TranslatableString > TranslatableStrings
Definition: TranslatableString.h:295
ImportPlugin
Base class for FlacImportPlugin, LOFImportPlugin, MP3ImportPlugin, OggImportPlugin and PCMImportPlugi...
Definition: ImportPlugin.h:67
Tags
ID3 Tags (for MP3)
Definition: Tags.h:74
ImportFileHandle::GetFileUncompressedBytes
virtual ByteCount GetFileUncompressedBytes()=0
BasicUI::ProgressResult
ProgressResult
Definition: BasicUI.h:145
UnusableImportPlugin
Used in place of a real plug in for plug ins that have not been compiled or are not available in this...
Definition: ImportPlugin.h:165
ImportFileHandle::GetStreamInfo
virtual const TranslatableStrings & GetStreamInfo()=0
UnusableImportPlugin::mExtensions
const FileExtensions mExtensions
Definition: ImportPlugin.h:186
ImportFileHandle::mProgress
std::unique_ptr< ProgressDialog > mProgress
Definition: ImportPlugin.h:159
wxArrayStringEx
Extend wxArrayString with move operations and construction and insertion fromstd::initializer_list.
Definition: wxArrayStringEx.h:18
ImportPlugin::mExtensions
const FileExtensions mExtensions
Definition: ImportPlugin.h:99
UnusableImportPlugin::SupportsExtension
bool SupportsExtension(const FileExtension &extension)
Definition: ImportPlugin.h:179
FileExtension
wxString FileExtension
File extension, not including any leading dot.
Definition: Identifier.h:224
ProgressDialog
ProgressDialog Class.
Definition: ProgressDialog.h:51
FilePath
wxString FilePath
Definition: Project.h:20
UnusableImportPlugin::GetPluginFormatDescription
TranslatableString GetPluginFormatDescription()
Definition: ImportPlugin.h:174
Identifier.h
ImportPlugin::Open
virtual std::unique_ptr< ImportFileHandle > Open(const FilePath &Filename, AudacityProject *)=0
ImportFileHandle::mFilename
FilePath mFilename
Definition: ImportPlugin.h:158
ImportFileHandle
An ImportFileHandle for data.
Definition: ImportPlugin.h:107
ImportFileHandle::SetStreamUsage
virtual void SetStreamUsage(wxInt32 StreamID, bool Use)=0
WaveTrackFactory
Used to create or clone a WaveTrack, with appropriate context from the project that will own the trac...
Definition: WaveTrack.h:710
Internat.h
sampleFormat
sampleFormat
Definition: SampleFormat.h:29
Types.h
wxArrayStringEx.h
ImportFileHandle::GetFileDescription
virtual TranslatableString GetFileDescription()=0
BasicUI
Definition: Export.h:39
Track
Abstract base class for an object holding data associated with points on a time axis.
Definition: Track.h:239
ImportPlugin::~ImportPlugin
virtual ~ImportPlugin()
ImportFileHandle::GetStreamCount
virtual wxInt32 GetStreamCount()=0
AudacityProject
The top-level handle to an Audacity project. It serves as a source of events that other objects can b...
Definition: Project.h:92
UnusableImportPlugin::mFormatName
TranslatableString mFormatName
Definition: ImportPlugin.h:185
ImportPlugin::GetPluginStringID
virtual wxString GetPluginStringID()=0
ImportFileHandle::ByteCount
unsigned long long ByteCount
Definition: ImportPlugin.h:127
ImportFileHandle::Import
virtual ProgressResult Import(WaveTrackFactory *trackFactory, TrackHolders &outTracks, Tags *tags)=0
SampleFormat.h