Audacity 3.2.0
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#include "AcidizerTags.h"
49#include "Identifier.h"
50#include "Internat.h"
51#include "wxArrayStringEx.h"
52#include <memory>
53#include <optional>
54
55class AudacityProject;
57class Track;
58class TrackList;
60class Tags;
61
63
65
66class IMPORT_EXPORT_API ImportPlugin /* not final */
67{
68public:
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
86
87 virtual TranslatableString FailureHint() const;
88
89 bool SupportsExtension(const FileExtension &extension);
90
91 // Open the given file, returning true if it is in a recognized
92 // format, false otherwise. This puts the importer into the open
93 // state.
94 virtual std::unique_ptr<ImportFileHandle> Open(
95 const FilePath &Filename, AudacityProject*) = 0;
96
97 virtual ~ImportPlugin();
98
99protected:
100
101 ImportPlugin(FileExtensions supportedExtensions);
102
104};
105
106
107class WaveTrack;
108using TrackHolders = std::vector<std::shared_ptr<TrackList>>;
109
110class IMPORT_EXPORT_API ImportFileHandle /* not final */
111{
112public:
113
114 using ByteCount = unsigned long long;
115
117
118 virtual FilePath GetFilename() const = 0;
119
120 virtual TranslatableString GetErrorMessage() const;
121
122 // This is similar to GetPluginFormatDescription, but if possible the
123 // importer will return a more specific description of the
124 // specific file that is open.
126
127 // Return an estimate of how many bytes the file will occupy once
128 // imported. In principle this may exceed main memory, so don't use
129 // size_t.
131
132 // Return number of elements in stream list
133 virtual wxInt32 GetStreamCount() = 0;
134
135 // Return stream descriptions list, before Import() is called
136 virtual const TranslatableStrings &GetStreamInfo() = 0;
137
138 // Set stream "import/don't import" flag, before Import() is called
139 virtual void SetStreamUsage(wxInt32 StreamID, bool Use) = 0;
140
141 // do the actual import, creating whatever tracks are necessary with
142 // the WaveTrackFactory and calling the progress callback every iteration
143 // through the importing loop
144 // The given Tags and AcidizerTags structures may also be modified.
145 // In case of errors or exceptions, it is not necessary to leave outTracks,
146 // tags or acidTags unmodified. If resulting outTracks is not empty, then
147 // each member of it must be a nonempty vector.
148 virtual void Import(
149 ImportProgressListener& progressListener, WaveTrackFactory* trackFactory,
150 TrackHolders& outTracks, Tags* tags,
151 std::optional<LibFileFormats::AcidizerTags>& acidTags) = 0;
152
153 virtual void Cancel() = 0;
154
155 virtual void Stop() = 0;
156};
157
158class IMPORT_EXPORT_API ImportFileHandleEx : public ImportFileHandle
159{
161 bool mCancelled{false};
162 bool mStopped{false};
163public:
164 ImportFileHandleEx(const FilePath& filename);
165
166 FilePath GetFilename() const override;
167 void Cancel() override;
168 void Stop() override;
169
170protected:
171 void BeginImport();
172 bool IsCancelled() const noexcept;
173 bool IsStopped() const noexcept;
174};
175
176class IMPORT_EXPORT_API UnusableImportPlugin
177{
178public:
180 const TranslatableString &formatName, FileExtensions extensions):
181 mFormatName(formatName),
182 mExtensions( std::move( extensions ) )
183 {
184 }
185
187 {
188 return mFormatName;
189 }
190
191 bool SupportsExtension(const FileExtension &extension)
192 {
193 return mExtensions.Index(extension, false) != wxNOT_FOUND;
194 }
195
196private:
199};
200
201#endif
wxString FileExtension
File extension, not including any leading dot.
Definition: Identifier.h:224
std::vector< std::shared_ptr< TrackList > > TrackHolders
Definition: ImportRaw.h:24
wxString FilePath
Definition: Project.h:21
std::vector< TranslatableString > TranslatableStrings
The top-level handle to an Audacity project. It serves as a source of events that other objects can b...
Definition: Project.h:90
Base class for FlacImportFileHandle, LOFImportFileHandle, MP3ImportFileHandle, OggImportFileHandle an...
Definition: ImportPlugin.h:111
virtual ByteCount GetFileUncompressedBytes()=0
virtual TranslatableString GetFileDescription()=0
virtual wxInt32 GetStreamCount()=0
virtual void Cancel()=0
virtual const TranslatableStrings & GetStreamInfo()=0
unsigned long long ByteCount
Definition: ImportPlugin.h:114
virtual FilePath GetFilename() const =0
virtual void SetStreamUsage(wxInt32 StreamID, bool Use)=0
virtual void Stop()=0
virtual void Import(ImportProgressListener &progressListener, WaveTrackFactory *trackFactory, TrackHolders &outTracks, Tags *tags, std::optional< LibFileFormats::AcidizerTags > &acidTags)=0
virtual ~ImportFileHandle()
Base class for FlacImportPlugin, LOFImportPlugin, MP3ImportPlugin, OggImportPlugin and PCMImportPlugi...
Definition: ImportPlugin.h:67
virtual TranslatableString GetPluginFormatDescription()=0
virtual wxString GetPluginStringID()=0
virtual ~ImportPlugin()
const FileExtensions mExtensions
Definition: ImportPlugin.h:103
virtual std::unique_ptr< ImportFileHandle > Open(const FilePath &Filename, AudacityProject *)=0
Interface used to report on import state and progress.
ID3 Tags (for MP3)
Definition: Tags.h:73
Abstract base class for an object holding data associated with points on a time axis.
Definition: Track.h:122
A flat linked list of tracks supporting Add, Remove, Clear, and Contains, serialization of the list o...
Definition: Track.h:993
Holds a msgid for the translation catalog; may also bind format arguments.
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:177
bool SupportsExtension(const FileExtension &extension)
Definition: ImportPlugin.h:191
UnusableImportPlugin(const TranslatableString &formatName, FileExtensions extensions)
Definition: ImportPlugin.h:179
TranslatableString GetPluginFormatDescription()
Definition: ImportPlugin.h:186
TranslatableString mFormatName
Definition: ImportPlugin.h:197
const FileExtensions mExtensions
Definition: ImportPlugin.h:198
Used to create or clone a WaveTrack, with appropriate context from the project that will own the trac...
Definition: WaveTrack.h:1279
A Track that contains audio waveform data.
Definition: WaveTrack.h:227
Extend wxArrayString with move operations and construction and insertion fromstd::initializer_list.
STL namespace.