summaryrefslogtreecommitdiffstats
path: root/libk3b/plugin/k3baudioencoder.h
blob: b3fc01bc33f193abcfc15b5dfb5c7bc8f42cabd6 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
/* 
 *
 * $Id: k3baudioencoder.h 619556 2007-01-03 17:38:12Z trueg $
 * Copyright (C) 2003 Sebastian Trueg <trueg@k3b.org>
 *
 * This file is part of the K3b project.
 * Copyright (C) 1998-2007 Sebastian Trueg <trueg@k3b.org>
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 * See the file "COPYING" for the exact licensing terms.
 */

#ifndef _K3B_AUDIO_ENCODER_H_
#define _K3B_AUDIO_ENCODER_H_

#include <k3bplugin.h>

#include <k3bmsf.h>
#include "k3b_export.h"


/**
 * The base class for all audio encoders.
 * Do not be alarmed by the number of methods since most of them
 * do not need to be touched. They are just there to keep the API 
 * clean and extendable.
 *
 * see the skeleton files for further help.
 */
class LIBK3B_EXPORT K3bAudioEncoder : public K3bPlugin
{
  Q_OBJECT
  TQ_OBJECT

 public:
  K3bAudioEncoder( TQObject* tqparent = 0, const char* name = 0 );
  virtual ~K3bAudioEncoder();

  // TODO: if the following methods are to be activated the config methods in
  //       K3bPluginConfigWidget also need to be changed since they do not allow
  //       to use an extern config object yet.
  //       Perhaps these two methods should even go into K3bPlugin.
  /**
   * This calls readConfig using the k3bcore config object
   */
  // void readConfig();

  /**
   * Force the plugin to read it's configuration
   */
  // virtual void readConfig( KConfig* );

  TQString group() const { return "AudioEncoder"; }

  /**
   * This should return the fileextensions supported by the filetype written in the
   * encoder.
   * May return an empty list in which case the encoder will not be usable (this may come
   * in handy if the encoder is based on some external program or lib which is not 
   * available on runtime.)
   */
  virtual TQStringList extensions() const = 0;

  /**
   * The filetype as presented to the user.
   */
  virtual TQString fileTypeComment( const TQString& extension ) const = 0;

  /**
   * Determine the filesize of the encoded file (~)
   * default implementation returnes -1 (unknown)
   * First parameter is the extension to be used
   */
  virtual long long fileSize( const TQString&, const K3b::Msf& ) const { return -1; }

  /**
   * The default implementation openes the file for writing with 
   * writeData. Normally this does not need to be reimplemented.
   * @param extension the filetype to be used.
   *
   */
  virtual bool openFile( const TQString& extension, const TQString& filename, const K3b::Msf& length );


  /**
   * The default implementation returnes true if openFile (default implementation) has been
   * successfully called. Normally this does not need to be reimplemented but it has to be 
   * if openFile is reimplemented.
   */
  virtual bool isOpen() const;

  /**
   * The default implementation closes the file opened by openFile
   * (default implementation) 
   * Normally this does not need to be reimplemented but it has to be 
   * if openFile is reimplemented.
   */
  virtual void closeFile();

  /**
   * The default implementation returnes the filename set in openFile
   * or TQString() if no file has been opened.
   * Normally this does not need to be reimplemented but it has to be 
   * if openFile is reimplemented.
   */
  virtual const TQString& filename() const;

  enum MetaDataField {
    META_TRACK_TITLE,
    META_TRACK_ARTIST,
    META_TRACK_COMMENT,
    META_TRACK_NUMBER,
    META_ALBUM_TITLE,
    META_ALBUM_ARTIST,
    META_ALBUM_COMMENT,
    META_YEAR,
    META_GENRE };

  /**
   * Calling this method does only make sense after successfully
   * calling openFile and before calling encode.
   * This calls setMetaDataInternal.
   */
  void setMetaData( MetaDataField, const TQString& );

  /**
   * Returnes the amount of actually written bytes or -1 if an error
   * occurred.
   *
   * Be aware that the returned amount of written data may very well differ
   * from len since the data is encoded.
   */
  long encode( const char*, TQ_ULONG len );

  /**
   * Use this signal in case of an error to provide the user with information
   * about the problem.
   */
  virtual TQString lastErrorString() const;

 protected:
  /**
   * Called by the default implementation of openFile
   * This calls initEncoderInternal.
   */
  bool initEncoder( const TQString& extension, const K3b::Msf& length );

  /**
   * Called by the deafult implementation of openFile
   * This calls finishEncoderInternal.
   */
  void finishEncoder();

  /**
   * Use this to write the data to the file when
   * using the default implementation of openFile
   * Returnes the number of bytes actually written.
   */
  TQ_LONG writeData( const char*, TQ_ULONG len );

  /**
   * initzialize the decoder structures.
   * default implementation does nothing
   * this may already write data.
   */
  virtual bool initEncoderInternal( const TQString& extension, const K3b::Msf& length );

  /**
   * reimplement this if the encoder needs to do some
   * finishing touch.
   */
  virtual void finishEncoderInternal();

  /**
   * encode the data and write it with writeData (when using
   * the default)
   * The data will always be 16bit 44100 Hz stereo little endian samples.
   * Should return the amount of actually written bytes (may be 0) and -1
   * on error.
   */
  // TODO: use TQ_INT16* instead of char*
  // FIXME: why little endian while CDs use big endian???
  virtual long encodeInternal( const char*, TQ_ULONG len ) = 0;

  /**
   * default implementation does nothing
   * this may already write data.
   */
  virtual void setMetaDataInternal( MetaDataField, const TQString& );

  /**
   * Use this in combination with the default implementation of lastError()
   */
  void setLastError( const TQString& );

 private:
  class Private;
  Private* d;
};

#endif