File indexing completed on 2024-05-12 04:55:39
0001 /** 0002 * \file mp3file.h 0003 * Handling of tagged MP3 files. 0004 * 0005 * \b Project: Kid3 0006 * \author Urs Fleisch 0007 * \date 9 Jan 2003 0008 * 0009 * Copyright (C) 2003-2024 Urs Fleisch 0010 * 0011 * This file is part of Kid3. 0012 * 0013 * Kid3 is free software; you can redistribute it and/or modify 0014 * it under the terms of the GNU General Public License as published by 0015 * the Free Software Foundation; either version 2 of the License, or 0016 * (at your option) any later version. 0017 * 0018 * Kid3 is distributed in the hope that it will be useful, 0019 * but WITHOUT ANY WARRANTY; without even the implied warranty of 0020 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 0021 * GNU General Public License for more details. 0022 * 0023 * You should have received a copy of the GNU General Public License 0024 * along with this program. If not, see <http://www.gnu.org/licenses/>. 0025 */ 0026 0027 #pragma once 0028 0029 #include <QScopedPointer> 0030 #include "taggedfile.h" 0031 #include "tagconfig.h" 0032 0033 class ID3_Tag; 0034 class ID3_Field; 0035 class ID3_Frame; 0036 class QTextCodec; 0037 0038 /** List box item containing MP3 file */ 0039 class Mp3File : public TaggedFile { 0040 public: 0041 /** 0042 * Constructor. 0043 * 0044 * @param idx index in tagged file system model 0045 */ 0046 explicit Mp3File(const QPersistentModelIndex& idx); 0047 0048 /** 0049 * Destructor. 0050 */ 0051 ~Mp3File() override; 0052 0053 /** 0054 * Get key of tagged file format. 0055 * @return "Id3libMetadata". 0056 */ 0057 QString taggedFileKey() const override; 0058 0059 /** 0060 * Get features supported. 0061 * @return bit mask with Feature flags set. 0062 */ 0063 int taggedFileFeatures() const override; 0064 0065 /** 0066 * Read tags from file. 0067 * 0068 * @param force true to force reading even if tags were already read. 0069 */ 0070 void readTags(bool force) override; 0071 0072 /** 0073 * Write tags to file and rename it if necessary. 0074 * 0075 * @param force true to force writing even if file was not changed. 0076 * @param renamed will be set to true if the file was renamed, 0077 * i.e. the file name is no longer valid, else *renamed 0078 * is left unchanged 0079 * @param preserve true to preserve file time stamps 0080 * 0081 * @return true if ok, false if the file could not be written or renamed. 0082 */ 0083 bool writeTags(bool force, bool* renamed, bool preserve) override; 0084 0085 /** 0086 * Free resources allocated when calling readTags(). 0087 * 0088 * @param force true to force clearing even if the tags are modified 0089 */ 0090 void clearTags(bool force) override; 0091 0092 /** 0093 * Remove frames. 0094 * 0095 * @param tagNr tag number 0096 * @param flt filter specifying which frames to remove 0097 */ 0098 void deleteFrames(Frame::TagNumber tagNr, const FrameFilter& flt) override; 0099 0100 /** 0101 * Check if tag information has already been read. 0102 * 0103 * @return true if information is available, 0104 * false if the tags have not been read yet, in which case 0105 * hasTag() does not return meaningful information. 0106 */ 0107 bool isTagInformationRead() const override; 0108 0109 /** 0110 * Check if file has a tag. 0111 * 0112 * @param tagNr tag number 0113 * @return true if a tag is available. 0114 * @see isTagInformationRead() 0115 */ 0116 bool hasTag(Frame::TagNumber tagNr) const override; 0117 0118 /** 0119 * Check if tags are supported by the format of this file. 0120 * 0121 * @param tagNr tag number 0122 * @return true. 0123 */ 0124 bool isTagSupported(Frame::TagNumber tagNr) const override; 0125 0126 /** 0127 * Get technical detail information. 0128 * 0129 * @param info the detail information is returned here 0130 */ 0131 void getDetailInfo(DetailInfo& info) const override; 0132 0133 /** 0134 * Get duration of file. 0135 * 0136 * @return duration in seconds, 0137 * 0 if unknown. 0138 */ 0139 unsigned getDuration() const override; 0140 0141 /** 0142 * Get file extension including the dot. 0143 * 0144 * @return file extension ".mp3". 0145 */ 0146 QString getFileExtension() const override; 0147 0148 /** 0149 * Get the format of tag. 0150 * 0151 * @param tagNr tag number 0152 * @return string describing format of tag, 0153 * e.g. "ID3v1.1", "ID3v2.3", "ID3v2.4". 0154 */ 0155 QString getTagFormat(Frame::TagNumber tagNr) const override; 0156 0157 /** 0158 * Get a specific frame from the tags. 0159 * 0160 * @param tagNr tag number 0161 * @param type frame type 0162 * @param frame the frame is returned here 0163 * 0164 * @return true if ok. 0165 */ 0166 bool getFrame(Frame::TagNumber tagNr, Frame::Type type, Frame& frame) const override; 0167 0168 /** 0169 * Set a frame in the tags. 0170 * 0171 * @param tagNr tag number 0172 * @param frame frame to set 0173 * 0174 * @return true if ok. 0175 */ 0176 bool setFrame(Frame::TagNumber tagNr, const Frame& frame) override; 0177 0178 /** 0179 * Add a frame in the tags. 0180 * 0181 * @param tagNr tag number 0182 * @param frame frame to add, a field list may be added by this method 0183 * 0184 * @return true if ok. 0185 */ 0186 bool addFrame(Frame::TagNumber tagNr, Frame& frame) override; 0187 0188 /** 0189 * Delete a frame from the tags. 0190 * 0191 * @param tagNr tag number 0192 * @param frame frame to delete. 0193 * 0194 * @return true if ok. 0195 */ 0196 bool deleteFrame(Frame::TagNumber tagNr, const Frame& frame) override; 0197 0198 /** 0199 * Get all frames in tag. 0200 * 0201 * @param tagNr tag number 0202 * @param frames frame collection to set. 0203 */ 0204 void getAllFrames(Frame::TagNumber tagNr, FrameCollection& frames) override; 0205 0206 /** 0207 * Get a list of frame IDs which can be added. 0208 * @param tagNr tag number 0209 * @return list with frame IDs. 0210 */ 0211 QStringList getFrameIds(Frame::TagNumber tagNr) const override; 0212 0213 /** 0214 * Add a suitable field list for the frame if missing. 0215 * If a frame is created, its field list is empty. This method will create 0216 * a field list appropriate for the frame type and tagged file type if no 0217 * field list exists. 0218 * @param tagNr tag number 0219 * @param frame frame where field list is added 0220 */ 0221 void addFieldList(Frame::TagNumber tagNr, Frame& frame) const override; 0222 0223 /** 0224 * Notify about configuration change. 0225 * This method shall be called when the configuration changes. 0226 */ 0227 static void notifyConfigurationChange(); 0228 0229 private: 0230 Mp3File(const Mp3File&); 0231 Mp3File& operator=(const Mp3File&); 0232 0233 /** 0234 * Set track. 0235 * 0236 * @param tag ID3 tag 0237 * @param num number to set, 0 to remove field. 0238 * @param numTracks total number of tracks, <=0 to ignore 0239 * 0240 * @return true if the field was changed. 0241 */ 0242 bool setTrackNum(ID3_Tag* tag, int num, int numTracks = 0) const; 0243 0244 /** 0245 * Set the fields in an id3lib frame from the field in the frame. 0246 * 0247 * @param id3Frame id3lib frame 0248 * @param frame frame with fields 0249 */ 0250 void setId3v2Frame(ID3_Frame* id3Frame, const Frame& frame) const; 0251 0252 /** 0253 * Create an id3lib frame from a frame. 0254 * @param frame frame 0255 * @return id3lib frame, 0 if invalid. 0256 */ 0257 ID3_Frame* createId3FrameFromFrame(Frame& frame) const; 0258 0259 /** 0260 * Set the encoding to be used for tag 1. 0261 * 0262 * @param name of encoding, default is ISO 8859-1 0263 */ 0264 static void setTextEncodingV1(const QString& name); 0265 0266 /** 0267 * Set the default text encoding. 0268 * 0269 * @param textEnc default text encoding 0270 */ 0271 static void setDefaultTextEncoding(TagConfig::TextEncoding textEnc); 0272 0273 /** ID3v1 tags */ 0274 QScopedPointer<ID3_Tag> m_tagV1; 0275 0276 /** ID3v2 tags */ 0277 QScopedPointer<ID3_Tag> m_tagV2; 0278 };