1 /********************************************************** 2 * 3 * libmp3splt -- library based on mp3splt v2.1c, 4 * for mp3/ogg splitting without decoding 5 * 6 * Copyright (c) 2002-2005 M. Trotta - <mtrotta@users.sourceforge.net> 7 * Copyright (c) 2005-2014 Alexandru Munteanu - m@ioalex.net 8 * 9 * And others ... see the AUTHORS file provided with libmp3splt source. 10 * 11 * http://mp3splt.sourceforge.net 12 * 13 *********************************************************/ 14 15 /********************************************************** 16 * 17 * This program is free software; you can redistribute it and/or 18 * modify it under the terms of the GNU General Public License 19 * as published by the Free Software Foundation; either version 2 20 * of the License, or (at your option) any later version. 21 * 22 * This program is distributed in the hope that it will be useful, 23 * but WITHOUT ANY WARRANTY; without even the implied warranty of 24 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 25 * GNU General Public License for more details. 26 * 27 * You should have received a copy of the GNU General Public License 28 * along with this program; if not, write to the Free Software 29 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, 30 * USA. 31 * 32 *********************************************************/ 33 34 /** 35 * \file mp3splt.h 36 * 37 * \brief libmp3splt API 38 */ 39 40 /** \mainpage API documentation 41 42 This is the documentation of the library that stands behind mp3splt (version >= 2.2) and mp3splt-gtk.\n 43 Libmp3splt is licensed under the <a href="http://www.gnu.org/licenses/gpl-2.0.html">GNU General 44 Public License version 2</a>.\n 45 Source code and binaries can be found on the <a 46 href="http://mp3splt.sourceforge.net/mp3splt_page/home.php">mp3splt-project home page</a>.\n 47 48 Some of the library features include: 49 - losslessly split of mp3 (using <a href="http://www.underbit.com/products/mad/">libmad</a>), 50 ogg vorbis (using <a href="http://xiph.org/vorbis/">libvorbis</a>), 51 <a href="https://xiph.org/flac/">FLAC</a> files 52 - extensibility to other audio formats using plugins 53 - querying tags from <a href="http://tracktype.org">tracktype.org</a> 54 - split on silences 55 - trim using silence detection 56 - split by a fixed time or equal time length 57 - CDDB, CUE, audacity labels import 58 - CUE export 59 - extract tracks created with <a href="http://mp3wrap.sourceforge.net">Mp3Wrap</a> or AlbumWrap 60 61 In order to use the library in another project: 62 - Start with the \ref splt_state_ section, continue with \ref splt_filepaths_ and 63 \ref splt_callback_ and then finish with \ref splt_splitpoints_ and \ref splt_split_. 64 - A minimal example on how to use this library can be found in \ref minimal.c 65 - For any other example or question, contact Alexandru Munteanu at m@ioalex.net. 66 67 For writing a plugin to support other file type: 68 - Look at the #splt_plugin_func from the \ref splt_plugin_api. 69 70 A list of <a href="modules.html">all modules</a> is also available. 71 */ 72 73 /** \example minimal.c 74 * A minimal usage example. 75 */ 76 77 /** 78 * \defgroup using_libmp3splt Using libmp3splt 79 */ 80 81 #ifndef MP3SPLT_MP3SPLT_H 82 83 #include <sys/types.h> 84 85 #include "version.h" 86 87 /** 88 * @brief True value 89 */ 90 #define SPLT_TRUE 1 91 /** 92 * @brief False value 93 */ 94 #define SPLT_FALSE 0 95 96 /** 97 * \ingroup using_libmp3splt 98 * @defgroup splt_error_codes_ Confirmation and error codes 99 @{ 100 */ 101 102 /** 103 * @brief Confirmation and error codes. 104 * 105 * @see #mp3splt_get_strerror 106 */ 107 typedef enum { 108 SPLT_OK = 0, 109 110 SPLT_OK_SPLIT = 1, 111 SPLT_SPLITPOINT_BIGGER_THAN_LENGTH = 4, 112 SPLT_SILENCE_OK = 5, 113 SPLT_TIME_SPLIT_OK = 6, 114 SPLT_NO_SILENCE_SPLITPOINTS_FOUND = 7, 115 SPLT_OK_SPLIT_EOF = 8, 116 SPLT_LENGTH_SPLIT_OK = 9, 117 SPLT_TRIM_SILENCE_OK = 10, 118 119 SPLT_FREEDB_OK = 100, 120 SPLT_FREEDB_FILE_OK = 101, 121 SPLT_CDDB_OK = 102, 122 SPLT_CUE_OK = 103, 123 SPLT_FREEDB_MAX_CD_REACHED = 104, 124 SPLT_AUDACITY_OK = 105, 125 126 SPLT_DEWRAP_OK = 200, 127 128 SPLT_SYNC_OK = 300, 129 SPLT_MIGHT_BE_VBR = 301, 130 131 SPLT_ERR_SYNC = -300, 132 SPLT_ERR_NO_SYNC_FOUND = -301, 133 SPLT_ERR_TOO_MANY_SYNC_ERR = -302, 134 135 SPLT_OUTPUT_FORMAT_OK = 400, 136 SPLT_OUTPUT_FORMAT_AMBIGUOUS = 401, 137 138 SPLT_REGEX_OK = 800, 139 140 SPLT_ERROR_SPLITPOINTS = -1, 141 SPLT_ERROR_CANNOT_OPEN_FILE = -2, 142 SPLT_ERROR_INVALID = -3, 143 SPLT_ERROR_EQUAL_SPLITPOINTS = -5, 144 SPLT_ERROR_SPLITPOINTS_NOT_IN_ORDER = -6, 145 SPLT_ERROR_NEGATIVE_SPLITPOINT = -7, 146 SPLT_ERROR_INCORRECT_PATH = -8, 147 SPLT_ERROR_INCOMPATIBLE_OPTIONS = -10, 148 SPLT_ERROR_INPUT_OUTPUT_SAME_FILE = -12, 149 SPLT_ERROR_CANNOT_ALLOCATE_MEMORY = -15, 150 SPLT_ERROR_CANNOT_OPEN_DEST_FILE = -16, 151 SPLT_ERROR_CANT_WRITE_TO_OUTPUT_FILE = -17, 152 SPLT_ERROR_WHILE_READING_FILE = -18, 153 SPLT_ERROR_SEEKING_FILE = -19, 154 SPLT_ERROR_BEGIN_OUT_OF_FILE = -20, 155 SPLT_ERROR_INEXISTENT_FILE = -21, 156 SPLT_SPLIT_CANCELLED = -22, 157 SPLT_ERROR_LIBRARY_LOCKED = -24, 158 SPLT_ERROR_STATE_NULL = -25, 159 SPLT_ERROR_NEGATIVE_TIME_SPLIT = -26, 160 SPLT_ERROR_CANNOT_CREATE_DIRECTORY = -27, 161 SPLT_ERROR_CANNOT_CLOSE_FILE = -28, 162 SPLT_ERROR_NO_PLUGIN_FOUND = -29, 163 SPLT_ERROR_CANNOT_INIT_LIBLTDL = -30, 164 SPLT_ERROR_CRC_FAILED = -31, 165 SPLT_ERROR_NO_PLUGIN_FOUND_FOR_FILE = -32, 166 SPLT_ERROR_PLUGIN_ERROR = -33, 167 SPLT_ERROR_TIME_SPLIT_VALUE_INVALID = -34, 168 SPLT_ERROR_LENGTH_SPLIT_VALUE_INVALID = -35, 169 SPLT_ERROR_CANNOT_GET_TOTAL_TIME = -36, 170 SPLT_ERROR_LIBID3 = -37, 171 SPLT_ERROR_FAILED_BITRESERVOIR = -38, 172 173 SPLT_FREEDB_ERROR_INITIALISE_SOCKET = -101, 174 SPLT_FREEDB_ERROR_CANNOT_GET_HOST = -102, 175 SPLT_FREEDB_ERROR_CANNOT_OPEN_SOCKET = -103, 176 SPLT_FREEDB_ERROR_CANNOT_CONNECT = -104, 177 SPLT_FREEDB_ERROR_CANNOT_SEND_MESSAGE = -105, 178 SPLT_FREEDB_ERROR_INVALID_SERVER_ANSWER = -106, 179 SPLT_FREEDB_ERROR_SITE_201 = -107, 180 SPLT_FREEDB_ERROR_SITE_200 = -108, 181 SPLT_FREEDB_ERROR_BAD_COMMUNICATION = -109, 182 SPLT_FREEDB_ERROR_GETTING_INFOS = -110, 183 SPLT_FREEDB_NO_CD_FOUND = -111, 184 SPLT_FREEDB_ERROR_CANNOT_RECV_MESSAGE = -112, 185 SPLT_INVALID_CUE_FILE = -115, 186 SPLT_INVALID_CDDB_FILE = -116, 187 SPLT_FREEDB_NO_SUCH_CD_IN_DATABASE = -118, 188 SPLT_FREEDB_ERROR_SITE = -119, 189 SPLT_FREEDB_ERROR_CANNOT_DISCONNECT = -120, 190 SPLT_FREEDB_ERROR_PROXY_NOT_SUPPORTED = -121, 191 SPLT_ERROR_INTERNAL_SHEET = -122, 192 SPLT_ERROR_INTERNAL_SHEET_TYPE_NOT_SUPPORTED = -123, 193 194 SPLT_DEWRAP_ERR_FILE_LENGTH = -200, 195 SPLT_DEWRAP_ERR_VERSION_OLD = -201, 196 SPLT_DEWRAP_ERR_NO_FILE_OR_BAD_INDEX = -202, 197 SPLT_DEWRAP_ERR_FILE_DAMAGED_INCOMPLETE = -203, 198 SPLT_DEWRAP_ERR_FILE_NOT_WRAPED_DAMAGED = -204, 199 200 SPLT_OUTPUT_FORMAT_ERROR = -400, 201 202 SPLT_ERROR_INEXISTENT_SPLITPOINT = -500, 203 204 SPLT_PLUGIN_ERROR_UNSUPPORTED_FEATURE = -600, 205 206 SPLT_INVALID_AUDACITY_FILE = -700, 207 208 SPLT_INVALID_REGEX = -800, 209 SPLT_REGEX_NO_MATCH = -801, 210 SPLT_REGEX_UNAVAILABLE = -802, 211 212 SPLT_ERROR_NO_AUTO_ADJUST_FOUND = -900, 213 214 SPLT_ERROR_INVALID_CODE = -1000, 215 } splt_code; 216 217 //@} 218 219 /** 220 * \ingroup using_libmp3splt 221 * @defgroup splt_state_ Initialisation of the main state 222 //@{ 223 */ 224 225 /** 226 * @brief Main structure used in libmp3splt. 227 * All members are private. 228 * 229 * @see #mp3splt_new_state, #mp3splt_free_state 230 */ 231 typedef struct _splt_state splt_state; 232 233 /** 234 * @brief Creates a new #splt_state structure. 235 * 236 * \note #mp3splt_find_plugins must to be called after. 237 * 238 * @param[out] error Possible error; can be NULL. 239 * @return A newly allocated #splt_state. 240 * 241 * @see #mp3splt_free_state 242 */ 243 splt_state *mp3splt_new_state(splt_code *error); 244 245 /** 246 * @brief Free the memory of the \p state. 247 * 248 * @param[in] state Main state to be freed. 249 * @return Possible error. 250 * 251 * @see #mp3splt_new_state 252 */ 253 splt_code mp3splt_free_state(splt_state *state); 254 255 /** 256 * @brief Appends an additional directory where plugins are searched. 257 * 258 * @param[in] state Main state. 259 * @param[in] directory Additional directory where plugins will be searched. 260 * @return Possible error. 261 * 262 * @see #mp3splt_find_plugins 263 */ 264 splt_code mp3splt_append_plugins_scan_dir(splt_state *state, const char *directory); 265 266 /** 267 * @brief Finds the plugins in the plugins directories. 268 * This function must be called after the \p state initialisation. 269 * 270 * @param[in] state Main state. 271 * @return Possible error. 272 * 273 * @see #mp3splt_append_plugins_scan_dir 274 */ 275 splt_code mp3splt_find_plugins(splt_state *state); 276 277 //@} 278 279 /** @addtogroup splt_error_codes_ 280 * @{ 281 */ 282 283 /** 284 * @brief Returns the error message of the \p error. 285 * 286 * Please note that you have to call this function right after receiving the \p error because the 287 * returned error message can contain information that is replaced if other error occurs. 288 * 289 * @param[in] state Main state. 290 * @param[in] error Possible error; can be NULL. 291 * @return Error message of the \p error. Result must be freed. 292 */ 293 char *mp3splt_get_strerror(splt_state *state, splt_code error); 294 295 //@} 296 297 /** 298 * \ingroup using_libmp3splt 299 * @defgroup splt_options_ Options 300 @{ 301 */ 302 303 /** 304 * @brief Split options. 305 * 306 * Use #mp3splt_set_int_option, #mp3splt_set_long_option and #mp3splt_set_float_option to set those 307 * options. 308 * 309 * Use #mp3splt_get_int_option, #mp3splt_get_long_option and #mp3splt_get_float_option to get those 310 * options. 311 */ 312 typedef enum { 313 /** 314 * Pretend to split the file, without actually creating output files. 315 * This option works in all modes except error mode and dewrap split. 316 * 317 * Int option that can take the values #SPLT_TRUE or #SPLT_FALSE. 318 * 319 * Default is #SPLT_FALSE 320 */ 321 SPLT_OPT_PRETEND_TO_SPLIT = 1, 322 /** 323 * If quiet return less messages and don't do mp3 CRC check. 324 * 325 * Int option that can take the values #SPLT_TRUE or #SPLT_FALSE. 326 * 327 * Default is #SPLT_FALSE 328 */ 329 SPLT_OPT_QUIET_MODE, 330 /** 331 * If we return debug messages or not. 332 * 333 * Int option that can take the values #SPLT_TRUE or #SPLT_FALSE. 334 * 335 * Default is #SPLT_FALSE 336 */ 337 SPLT_OPT_DEBUG_MODE, 338 /** 339 * The type of the split. 340 * 341 * Int option that can take the values from #splt_split_mode_options. 342 * 343 * Default is #SPLT_OPTION_NORMAL_MODE 344 */ 345 SPLT_OPT_SPLIT_MODE, 346 /** 347 * What tags to put in the output split files. 348 * 349 * Int option that can take the values from #splt_tags_options. 350 * 351 * Default is #SPLT_CURRENT_TAGS 352 */ 353 SPLT_OPT_TAGS, 354 /** 355 * For mp3 files, if we write the Xing header. 356 * 357 * Int option that can take the values #SPLT_TRUE or #SPLT_FALSE. 358 * 359 * Default is #SPLT_TRUE 360 */ 361 SPLT_OPT_XING, 362 /** 363 * If this option is #SPLT_TRUE, we create directories from the output 364 * filenames without parsing for illegal characters the output filenames. 365 * 366 * Otherwise, we parse for illegal characters the filenames and replace 367 * them with '_'. 368 * 369 * Int option that can take the values #SPLT_TRUE or #SPLT_FALSE. 370 * 371 * Default is #SPLT_FALSE 372 */ 373 SPLT_OPT_CREATE_DIRS_FROM_FILENAMES, 374 /** 375 * Defines how the output filenames are created. 376 * 377 * Int option that can take values from #splt_output_filenames_options. 378 * 379 * Default is #SPLT_OUTPUT_DEFAULT 380 */ 381 SPLT_OPT_OUTPUT_FILENAMES, 382 /** 383 * For mp3 files, force to use the frame mode or not. 384 * The frame mode processes the file frame by frame and 385 * it is useful when splitting VBR (Variable Bit Rate) files. 386 * Frame mode provides higher precision but is slower. 387 * 388 * Int option that can take the values #SPLT_TRUE or #SPLT_FALSE. 389 * 390 * Default is #SPLT_FALSE 391 */ 392 SPLT_OPT_FRAME_MODE, 393 /** 394 * If we use silence detection to auto-adjust splitpoints 395 * 396 * Int option that can take the values #SPLT_TRUE or #SPLT_FALSE. 397 * 398 * Default is #SPLT_FALSE 399 */ 400 SPLT_OPT_AUTO_ADJUST, 401 /** 402 * If the input is not seekable. 403 * This allows splitting mp3 streams which can be read only one time 404 * and can't be seeked. 405 * 406 * Int option that can take the values #SPLT_TRUE or #SPLT_FALSE. 407 * 408 * Default is #SPLT_FALSE 409 */ 410 SPLT_OPT_INPUT_NOT_SEEKABLE, 411 /** 412 * The desired number of tracks when having a #SPLT_OPTION_SILENCE_MODE split 413 * 414 * Int option that can take positive integer values. 415 * 0 means that we split as many files we find. 416 * 417 * Default is #SPLT_DEFAULT_PARAM_TRACKS 418 */ 419 SPLT_OPT_PARAM_NUMBER_TRACKS, 420 /** 421 * The desired number of shots when having a 422 * #SPLT_OPTION_SILENCE_MODE or #SPLT_OPTION_TRIM_SILENCE_MODE split 423 * or using the #SPLT_OPT_AUTO_ADJUST option 424 * 425 * Int option that can take positive integer values. 426 * It defines the number of shots to be found after the silence. 427 * Decrease this value if you need to split files having closer silence points. 428 * 429 * Default is #SPLT_DEFAULT_PARAM_SHOTS 430 */ 431 SPLT_OPT_PARAM_SHOTS, 432 /** 433 * Used to remove silence between the split tracks when having a #SPLT_OPTION_SILENCE_MODE split. 434 * 435 * Int option that can take the values #SPLT_TRUE or #SPLT_FALSE. 436 * 437 * Default is #SPLT_FALSE 438 */ 439 SPLT_OPT_PARAM_REMOVE_SILENCE, 440 /** 441 * The time to auto-adjust before and after splitpoint 442 * when having the #SPLT_OPT_AUTO_ADJUST option. 443 * 444 * Int option that can take positive integer values. 445 * 446 * Default is #SPLT_DEFAULT_PARAM_GAP 447 */ 448 SPLT_OPT_PARAM_GAP, 449 /** 450 * Enables or disables writing the log file containing splitpoints 451 * found with silence detection. 452 * 453 * Int option that can take the values #SPLT_TRUE or #SPLT_FALSE. 454 * 455 * Default is #SPLT_FALSE 456 */ 457 SPLT_OPT_ENABLE_SILENCE_LOG, 458 /** 459 * For mp3 files, tags version to be written in output files. 460 * 461 * Int option that can take the values 0, 1, 2 or 12. 462 * 0 is for 'same tags versions as the input file', 463 * 1 is for ID3v1, 2 for ID3v2 and 12 for both ID3v1 and ID3v2. 464 * 465 * Default is 0 466 */ 467 SPLT_OPT_FORCE_TAGS_VERSION, 468 /** 469 * Number of files to be created when splitting by equal time length 470 * with #SPLT_OPTION_LENGTH_MODE. 471 * 472 * Int option that can take positive values. 473 * 474 * Default is 1 475 */ 476 SPLT_OPT_LENGTH_SPLIT_FILE_NUMBER, 477 /** 478 * Enables or disables replacing tags in tags. 479 * If set to #SPLT_TRUE with an album 'myalbum_\@t' and a title 'mysong' 480 * will result in album 'myalbum_mysong'. 481 * 482 * Int option that can take the values #SPLT_TRUE or #SPLT_FALSE. 483 * 484 * Default is #SPLT_FALSE 485 */ 486 SPLT_OPT_REPLACE_TAGS_IN_TAGS, 487 /** 488 * Time to be added to each end splitpoint in order to overlap 489 * the resulting files (in hundreths of seconds). 490 * 491 * Long option that can take positive values. 492 * 493 * Default is 0 494 */ 495 SPLT_OPT_OVERLAP_TIME, 496 /** 497 * Time of the output files for the #SPLT_OPTION_TIME_MODE split (in 498 * hundreths of seconds). 499 * 500 * Long option that can take positive values. 501 * 502 * Default is 6000 (one minute) 503 */ 504 SPLT_OPT_SPLIT_TIME, 505 /** 506 * The threshold level (dB) to be considered as silence. 507 * 508 * Threshold is used when having a #SPLT_OPTION_SILENCE_MODE, #SPLT_OPTION_TRIM_SILENCE_MODE 509 * or #SPLT_OPT_AUTO_ADJUST option. 510 * 511 * Float option that can take values between -96 and 0. 512 * 513 * Default is #SPLT_DEFAULT_PARAM_THRESHOLD 514 */ 515 SPLT_OPT_PARAM_THRESHOLD, 516 /** 517 * Offset of cutpoint inside the silence part when having a 518 * #SPLT_OPTION_SILENCE_MODE or #SPLT_OPT_AUTO_ADJUST option 519 * 520 * Float option that can take values between -2 and 2. 521 * 0 is the begin of silence and 1 the end. 522 * 523 * Default is #SPLT_DEFAULT_PARAM_OFFSET 524 */ 525 SPLT_OPT_PARAM_OFFSET, 526 /** 527 * Minimum number of silence seconds to be considered a valid splitpoint. 528 * All silences shorter than this value are discarded. 529 * 530 * Float option that can take positive float values. 531 * 532 * Default is #SPLT_DEFAULT_PARAM_MINIMUM_LENGTH 533 */ 534 SPLT_OPT_PARAM_MIN_LENGTH, 535 /** 536 * Minimum number of seconds to be considered a valid track. 537 * All tracks shorter than this value are discarded. 538 * 539 * Float option that can take positive float values. 540 * 541 * Default is #SPLT_DEFAULT_PARAM_MINIMUM_TRACK_LENGTH 542 */ 543 SPLT_OPT_PARAM_MIN_TRACK_LENGTH, 544 /** 545 * Minimum number of seconds to be considered a valid track. 546 * All tracks shorter than this value are joined with others. 547 * The difference between #SPLT_OPT_PARAM_MIN_TRACK_LENGTH is that using this option, 548 * no part from the original file is lost. 549 * 550 * Float option that can take positive float values. 551 * 552 * Default is #SPLT_DEFAULT_PARAM_MIN_TRACK_JOIN 553 */ 554 SPLT_OPT_PARAM_MIN_TRACK_JOIN, 555 /** 556 * Output format of the artist extracted from filename when 557 * using #SPLT_TAGS_FROM_FILENAME_REGEX. 558 * 559 * Int option that can take values as #splt_str_format. 560 * 561 * Default is #SPLT_NO_CONVERSION 562 */ 563 SPLT_OPT_ARTIST_TAG_FORMAT, 564 /** 565 * Output format of the album extracted from filename when 566 * using #SPLT_TAGS_FROM_FILENAME_REGEX. 567 * 568 * Int option that can take values as #splt_str_format. 569 * 570 * Default is #SPLT_NO_CONVERSION 571 */ 572 SPLT_OPT_ALBUM_TAG_FORMAT, 573 /** 574 * Output format of the title extracted from filename when 575 * using #SPLT_TAGS_FROM_FILENAME_REGEX. 576 * 577 * Int option that can take values as #splt_str_format. 578 * 579 * Default is #SPLT_NO_CONVERSION 580 */ 581 SPLT_OPT_TITLE_TAG_FORMAT, 582 /** 583 * Output format of the comment extracted from filename when 584 * using #SPLT_TAGS_FROM_FILENAME_REGEX. 585 * 586 * Int option that can take values as #splt_str_format. 587 * 588 * Default is #SPLT_NO_CONVERSION 589 */ 590 SPLT_OPT_COMMENT_TAG_FORMAT, 591 /** 592 * Replace underscores with space when setting tags from filename 593 * regex with #SPLT_TAGS_FROM_FILENAME_REGEX. 594 * 595 * Int option that can take the values #SPLT_TRUE or #SPLT_FALSE. 596 * 597 * Default is #SPLT_FALSE 598 */ 599 SPLT_OPT_REPLACE_UNDERSCORES_TAG_FORMAT, 600 /** 601 * When importing CUE files, sets the filename to split as the FILE 602 * CUE tag value if specified. 603 * 604 * Int option that can take the values #SPLT_TRUE or #SPLT_FALSE. 605 * 606 * Default is #SPLT_FALSE 607 */ 608 SPLT_OPT_SET_FILE_FROM_CUE_IF_FILE_TAG_FOUND, 609 /** 610 * When using the #SPLT_OPT_PARAM_REMOVE_SILENCE, this option allows you to keep some 611 * number of seconds of silence from the beginning of the output file 612 * (end of the silence segment). 613 * 614 * Float option that can take positive values. 615 * 616 * Default is #SPLT_DEFAULT_KEEP_SILENCE_LEFT 617 */ 618 SPLT_OPT_KEEP_SILENCE_LEFT, 619 /** 620 * When using the #SPLT_OPT_PARAM_REMOVE_SILENCE, this option allows you to keep some 621 * number of seconds of silence from the end of the output file 622 * (beginning of the silence segment). 623 * 624 * Float option that can take positive values. 625 * 626 * Default is #SPLT_DEFAULT_KEEP_SILENCE_RIGHT 627 */ 628 SPLT_OPT_KEEP_SILENCE_RIGHT, 629 /** 630 * When importing a cue file, use the REM NAME comment for each TRACK to set the 631 * splitpoint names instead of setting the splitpoint names from the tags. 632 * 633 * Int option that can take the values #SPLT_TRUE or #SPLT_FALSE. 634 * 635 * Default is #SPLT_FALSE 636 */ 637 SPLT_OPT_CUE_SET_SPLITPOINT_NAMES_FROM_REM_NAME, 638 /** 639 * Output or not a message that the CUE file has been created. 640 * 641 * Int option that can take the values #SPLT_TRUE or #SPLT_FALSE. 642 * 643 * Default is #SPLT_FALSE 644 */ 645 SPLT_OPT_CUE_DISABLE_CUE_FILE_CREATED_MESSAGE, 646 /** 647 * When adding cue or cddb tags, keep the option #SPLT_TAGS_ORIGINAL. 648 * When enabling this option, #mp3splt_read_original_tags must also be called. 649 * 650 * Int option that can take the values #SPLT_TRUE or #SPLT_FALSE. 651 * 652 * Default is #SPLT_FALSE 653 */ 654 SPLT_OPT_CUE_CDDB_ADD_TAGS_WITH_KEEP_ORIGINAL_TAGS, 655 /** 656 * Defines the encoding of the ID3V2 tags. 657 * 658 * Int option that can take the values from #splt_id3v2_encoding. 659 * 660 * Default is #SPLT_ID3V2_UTF8 661 */ 662 SPLT_OPT_ID3V2_ENCODING, 663 /** 664 * Defines the encoding of the input tags - used only for generating ID3V2 tags. 665 * 666 * Int option that can take the values from #splt_id3v2_encoding. 667 * 668 * Default is #SPLT_ID3V2_UTF8 669 */ 670 SPLT_OPT_INPUT_TAGS_ENCODING, 671 /** 672 * Defines the minimum theoretical time length to be created when using 673 * #SPLT_OPTION_TIME_MODE. 674 * It is useful to avoid creating the last segment too small. 675 * Time unit is in hundreths of seconds. 676 * 677 * Long option that can take positive values. 678 * 679 * Default is 0. 680 */ 681 SPLT_OPT_TIME_MINIMUM_THEORETICAL_LENGTH, 682 /** 683 * If #SPLT_TRUE, raise a warning when no auto-adjust silence is found when 684 * using the #SPLT_OPT_AUTO_ADJUST option. 685 * 686 * Int option that can take the values #SPLT_TRUE or #SPLT_FALSE. 687 * 688 * Default is #SPLT_FALSE. 689 */ 690 SPLT_OPT_WARN_IF_NO_AUTO_ADJUST_FOUND, 691 /** 692 * If #SPLT_TRUE, stop with error when no auto-adjust silence is found when 693 * using the #SPLT_OPT_AUTO_ADJUST option. 694 * 695 * Int option that can take the values #SPLT_TRUE or #SPLT_FALSE. 696 * 697 * Default is #SPLT_FALSE. 698 */ 699 SPLT_OPT_STOP_IF_NO_AUTO_ADJUST_FOUND, 700 /** 701 * If #SPLT_TRUE, decode flac frames before writing them in the output file and compute the md5sum 702 * to be stored in the FLAC header - this option decreases the performance of the split because of 703 * the decoding process - it might be twice slower. 704 * 705 * Int option that can take the values #SPLT_TRUE or #SPLT_FALSE. 706 * 707 * Default is #SPLT_FALSE. 708 */ 709 SPLT_OPT_DECODE_AND_WRITE_FLAC_MD5SUM_FOR_CREATED_FILES, 710 /** 711 * If #SPLT_TRUE, handles bit-reservoir for gapless playback when splitting. 712 * It currently works only for mp3 files. 713 * 714 * Int option that can take the values #SPLT_TRUE or #SPLT_FALSE. 715 * 716 * Default is #SPLT_FALSE. 717 */ 718 SPLT_OPT_HANDLE_BIT_RESERVOIR, 719 } splt_options; 720 721 /** 722 * @brief Split mode. Possible values for the #SPLT_OPT_SPLIT_MODE option. 723 */ 724 typedef enum { 725 /** 726 * Normal split mode - using splitpoints provided with #mp3splt_append_splitpoint. 727 */ 728 SPLT_OPTION_NORMAL_MODE, 729 /** 730 * Wrap split mode - split the files created with [mp3wrap](http://mp3wrap.sourceforge.net/) or albumwrap. 731 * To just find out the wrapped files, see #mp3splt_get_wrap_files. 732 */ 733 SPLT_OPTION_WRAP_MODE, 734 /** 735 * Silence detection split mode. 736 * To just find out the silence detection splitpoints, see #mp3splt_set_silence_points. 737 */ 738 SPLT_OPTION_SILENCE_MODE, 739 /** 740 * Trim silence detection split mode. 741 * To just find out the trim silence detection splitpoints, see #mp3splt_set_trim_silence_points. 742 */ 743 SPLT_OPTION_TRIM_SILENCE_MODE, 744 /** 745 * Synchronisation error split mode (mp3 only). 746 * It is useful to split large file derivated from a concatenation of smaller files. 747 */ 748 SPLT_OPTION_ERROR_MODE, 749 /** 750 * Create an indefinite number of smaller files with a fixed time length specified by 751 * #SPLT_OPT_SPLIT_TIME. 752 */ 753 SPLT_OPTION_TIME_MODE, 754 /** 755 * Split in #SPLT_OPT_LENGTH_SPLIT_FILE_NUMBER pieces of equal time length. 756 */ 757 SPLT_OPTION_LENGTH_MODE, 758 } splt_split_mode_options; 759 760 /** 761 * @brief Values for the #SPLT_OPT_ID3V2_ENCODING 762 */ 763 typedef enum { 764 /** 765 * Latin1 (ISO-8859-1) encoding for ID3v2 tags 766 */ 767 SPLT_ID3V2_LATIN1, 768 /** 769 * UTF-8 encoding for ID3v2 tags 770 */ 771 SPLT_ID3V2_UTF8, 772 /** 773 * UTF-16 encoding for ID3v2 tags 774 */ 775 SPLT_ID3V2_UTF16, 776 } splt_id3v2_encoding; 777 778 /** 779 * @brief Values for the #SPLT_OPT_OUTPUT_FILENAMES option 780 */ 781 typedef enum { 782 /** 783 * @brief Output filename format specified by #mp3splt_set_oformat. 784 */ 785 SPLT_OUTPUT_FORMAT, 786 /** 787 * @brief The default output; depends of the type of the split. 788 * 789 * Some defaults are #SPLT_DEFAULT_OUTPUT, #SPLT_DEFAULT_CDDB_CUE_OUTPUT, 790 * #SPLT_DEFAULT_SYNCERROR_OUTPUT, #SPLT_DEFAULT_SILENCE_OUTPUT and 791 * #SPLT_DEFAULT_TRIM_SILENCE_OUTPUT. 792 */ 793 SPLT_OUTPUT_DEFAULT, 794 /** 795 * @brief The names of the splitpoints provided by #mp3splt_append_splitpoint 796 * are used to generate the output filenames. 797 */ 798 SPLT_OUTPUT_CUSTOM 799 } splt_output_filenames_options; 800 801 /** 802 * @brief Default value for the #SPLT_OPT_PARAM_THRESHOLD option 803 */ 804 #define SPLT_DEFAULT_PARAM_THRESHOLD -48.0 805 /** 806 * @brief Default value for the #SPLT_OPT_PARAM_OFFSET option 807 */ 808 #define SPLT_DEFAULT_PARAM_OFFSET 0.8 809 /** 810 * @brief Default value for the #SPLT_OPT_PARAM_MIN_LENGTH option 811 */ 812 #define SPLT_DEFAULT_PARAM_MINIMUM_LENGTH 0.0 813 /** 814 * @brief Default value for the #SPLT_OPT_PARAM_MIN_TRACK_LENGTH option 815 */ 816 #define SPLT_DEFAULT_PARAM_MINIMUM_TRACK_LENGTH 0.0 817 /** 818 * @brief Default value for the #SPLT_OPT_PARAM_MIN_TRACK_JOIN option 819 */ 820 #define SPLT_DEFAULT_PARAM_MIN_TRACK_JOIN 0.0 821 /** 822 * @brief Default value for the #SPLT_OPT_PARAM_GAP option 823 */ 824 #define SPLT_DEFAULT_PARAM_GAP 30 825 /** 826 * @brief Default value for the #SPLT_OPT_PARAM_NUMBER_TRACKS option 827 */ 828 #define SPLT_DEFAULT_PARAM_TRACKS 0 829 /** 830 * @brief Default value for the #SPLT_OPT_PARAM_SHOTS option 831 */ 832 #define SPLT_DEFAULT_PARAM_SHOTS 25 833 /** 834 * @brief Default value for the #SPLT_OPT_KEEP_SILENCE_LEFT option 835 */ 836 #define SPLT_DEFAULT_KEEP_SILENCE_LEFT 0 837 /** 838 * @brief Default value for the #SPLT_OPT_KEEP_SILENCE_RIGHT option 839 */ 840 #define SPLT_DEFAULT_KEEP_SILENCE_RIGHT 0 841 842 /** 843 * @brief Values for the #SPLT_OPT_TAGS option 844 */ 845 typedef enum { 846 /** 847 * @brief Keep the tags of the original input file. 848 */ 849 SPLT_TAGS_ORIGINAL_FILE, 850 /** 851 * @brief Keep the tags issued from CDDB, CUE, tracktype.org or set by the user with #mp3splt_append_tags. 852 */ 853 SPLT_CURRENT_TAGS, 854 /** 855 * @brief Do not set any tags. 856 */ 857 SPLT_NO_TAGS, 858 /** 859 * @brief Sets tags from filename using regular expression provided by #mp3splt_set_input_filename_regex. 860 */ 861 SPLT_TAGS_FROM_FILENAME_REGEX, 862 } splt_tags_options; 863 864 /** 865 * @brief Default output for #SPLT_OPTION_NORMAL_MODE when using #SPLT_OUTPUT_DEFAULT. 866 * @see #mp3splt_set_oformat 867 */ 868 #define SPLT_DEFAULT_OUTPUT "@f_@mm_@ss_@h0h__@Mm_@Ss_@H0h" 869 870 /** 871 * @brief Output filename format for CDDB and CUE when using #SPLT_OUTPUT_DEFAULT. 872 * @see #mp3splt_set_oformat, #SPLT_OPT_OUTPUT_FILENAMES 873 */ 874 #define SPLT_DEFAULT_CDDB_CUE_OUTPUT "@A - @n - @t" 875 /** 876 * @brief Output filename format for #SPLT_OPTION_ERROR_MODE when using #SPLT_OUTPUT_DEFAULT. 877 * @see #mp3splt_set_oformat, #SPLT_OPT_OUTPUT_FILENAMES 878 */ 879 #define SPLT_DEFAULT_SYNCERROR_OUTPUT "@f_error_@n" 880 /** 881 * @brief Output filename format for #SPLT_OPTION_SILENCE_MODE when using #SPLT_OUTPUT_DEFAULT. 882 * @see #mp3splt_set_oformat, #SPLT_OPT_OUTPUT_FILENAMES 883 */ 884 #define SPLT_DEFAULT_SILENCE_OUTPUT "@f_silence_@n" 885 /** 886 * @brief Default output for the trim silence split. 887 * @see #mp3splt_set_oformat, #SPLT_OPT_OUTPUT_FILENAMES 888 */ 889 #define SPLT_DEFAULT_TRIM_SILENCE_OUTPUT "@f_trimmed" 890 891 /** 892 * @brief Values for #SPLT_OPT_ARTIST_TAG_FORMAT, #SPLT_OPT_ALBUM_TAG_FORMAT, 893 * #SPLT_OPT_TITLE_TAG_FORMAT and #SPLT_OPT_COMMENT_TAG_FORMAT when using 894 * #SPLT_TAGS_FROM_FILENAME_REGEX. 895 */ 896 typedef enum { 897 /** 898 * @brief Keep the input "as is" without further change. 899 */ 900 SPLT_NO_CONVERSION, 901 /** 902 * @brief Convert all characters of the input to lowercase. 903 */ 904 SPLT_TO_LOWERCASE, 905 /** 906 * @brief Convert all characters of the input to uppercase. 907 */ 908 SPLT_TO_UPPERCASE, 909 /** 910 * @brief Convert just the first character to uppercase. 911 */ 912 SPLT_TO_FIRST_UPPERCASE, 913 /** 914 * @brief Convert the first character of each word to uppercase. 915 */ 916 SPLT_TO_WORD_FIRST_UPPERCASE 917 } splt_str_format; 918 919 /** 920 * @brief Sets the value of an int option in the \p state. 921 * 922 * @param[in] state Main state. 923 * @param[in] option Target option from #splt_options. 924 * @param[in] value Value for the \p option. 925 * @return Possible error. 926 */ 927 splt_code mp3splt_set_int_option(splt_state *state, splt_options option, int value); 928 929 /** 930 * @brief Sets the value of a long option in the \p state. 931 * 932 * @param[in] state Main state. 933 * @param[in] option Target option from #splt_options. 934 * @param[in] value Value for the \p option. 935 * @return Possible error. 936 */ 937 splt_code mp3splt_set_long_option(splt_state *state, splt_options option, long value); 938 939 /** 940 * @brief Sets the value of a float option in the \p state. 941 * 942 * @param[in] state Main state. 943 * @param[in] option Target option from #splt_options. 944 * @param[in] value Value for the \p option. 945 * @return Possible error. 946 */ 947 splt_code mp3splt_set_float_option(splt_state *state, splt_options option, float value); 948 949 /** 950 * @brief Returns the value of an int option from the \p state. 951 * 952 * @param[in] state Main state. 953 * @param[in] option Target option from #splt_options. 954 * @param[out] error Possible error; can be NULL. 955 * @return Option value 956 */ 957 int mp3splt_get_int_option(splt_state *state, splt_options option, splt_code *error); 958 959 /** 960 * @brief Returns the value of a long option from the \p state. 961 * 962 * @param[in] state Main state. 963 * @param[in] option Target option from #splt_options. 964 * @param[out] error Possible error; can be NULL. 965 * @return Option value 966 */ 967 long mp3splt_get_long_option(splt_state *state, splt_options option, splt_code *error); 968 969 /** 970 * @brief Returns the value of a float option from the \p state. 971 * 972 * @param[in] state Main state. 973 * @param[in] option Target option from #splt_options. 974 * @param[out] error Possible error; can be NULL. 975 * @return Option value 976 */ 977 float mp3splt_get_float_option(splt_state *state, splt_options option, splt_code *error); 978 979 /** 980 * @brief Set the output format when using #SPLT_OUTPUT_FORMAT. 981 * 982 * @param[in] state Main state. 983 * @param[in] format Format of the output files. 984 * @return Possible error. 985 */ 986 splt_code mp3splt_set_oformat(splt_state *state, const char *format); 987 988 //@} 989 990 /** 991 * \ingroup using_libmp3splt 992 * @defgroup splt_filepaths_ Input filename and paths 993 @{ 994 */ 995 996 /** 997 * @brief Sets the input filename to split. 998 * 999 * @param[in] state Main state. 1000 * @param[in] filename Input filename to be split. 1001 * @return Possible error. 1002 */ 1003 splt_code mp3splt_set_filename_to_split(splt_state *state, const char *filename); 1004 1005 /** 1006 * @brief Sets the output directory where the split files will be created. 1007 * 1008 * @param[in] state Main state. 1009 * @param[in] path_of_split Output directory for the generated files. 1010 * @return Possible error. 1011 */ 1012 splt_code mp3splt_set_path_of_split(splt_state *state, const char *path_of_split); 1013 1014 /** 1015 * @brief Returns the filename to be split from the \p state. 1016 * 1017 * It is useful after importing a CUE file that provides a filename 1018 * with the FILE tag. 1019 * 1020 * @param[in] state Main state. 1021 * @return Possible error. 1022 * 1023 * @see #SPLT_OPT_SET_FILE_FROM_CUE_IF_FILE_TAG_FOUND 1024 */ 1025 const char *mp3splt_get_filename_to_split(splt_state *state); 1026 1027 /** 1028 * @brief Output filename for a M3U file that will be created in the output path. 1029 * 1030 * The M3U file will contain all the split files. 1031 * It will not be created if this function is not called. 1032 * 1033 * @param[in] state Main state. 1034 * @param[in] m3u_filename M3U filename. 1035 * @return Possible error. 1036 * 1037 * @see #mp3splt_set_path_of_split 1038 */ 1039 splt_code mp3splt_set_m3u_filename(splt_state *state, const char *m3u_filename); 1040 1041 /** 1042 * @brief Log filename for the #SPLT_OPTION_SILENCE_MODE split mode that will be created. 1043 * 1044 * The log filename is useful to find out the silence splitpoints with different parameters 1045 * without having to detect silence every time. 1046 * Note that if changing the #SPLT_OPT_PARAM_MIN_LENGTH or #SPLT_OPT_PARAM_THRESHOLD or the input 1047 * filename, the silence detection will still need be to be recomputed. 1048 * 1049 * By default, the filename is \p mp3splt.log. 1050 * 1051 * \note <i>Log file structure:</i>\n 1052 * The first line contains the name of the split file.\n 1053 * The second line contains the threshold and the minimum silence length.\n 1054 * The next lines contain each one three columns: 1055 * - the first column is the start position of the found silence (in seconds.fractions)\n 1056 * - the second column is the end position of the found silence (in seconds.fractions)\n 1057 * - the third column is the order of magnitude of the silence length; it is useful to 1058 * find out most probable silence points 1059 * 1060 * @param[in] state Main state. 1061 * @param[in] filename Log filename when detecting splitpoints from silence. 1062 * @return Possible error. 1063 * 1064 * @see #mp3splt_set_path_of_split 1065 */ 1066 splt_code mp3splt_set_silence_log_filename(splt_state *state, const char *filename); 1067 1068 /** 1069 * @brief Full log filename for the #SPLT_OPTION_SILENCE_MODE split mode that will be created. 1070 * 1071 * The full log filename is useful to draw the amplitude wave of the input file (in dB) in order 1072 * to choose a threshold. If this function is not called, no full log is written. 1073 * 1074 * \note <i>Full log file structure:</i>\n 1075 * The first column is a dummy column which is always zero, for plotting on zero axis purposes.\n 1076 * The second column is the time in seconds as double.\n 1077 * The third column is the dB level.\n 1078 * The fourth column is the silences shots counter.\n 1079 * The five column is the number of splitpoints found.\n 1080 * The sixth column is the start time of the silence spot found.\n 1081 * The seventh column is the end time of the silence spot found. 1082 * 1083 * Example of plotting the full log file with gnuplot: 1084 * \code 1085 * gnuplot -e "file='silence_logs.txt'; set decimalsign locale; set xlabel 'Time in seconds'; 1086 * plot file using 2:3 title 'Threshold', 1087 * file using 2:4 title 'Silence shots' with linespoints, 1088 * file using 2:5 title 'Number of silence points found' with fsteps, 1089 * file using 6:1 title 'Begin of silence', 1090 * file using 7:1 title 'End of silence' with points; 1091 * pause -1" 1092 * \endcode 1093 * 1094 * @param[in] state Main state. 1095 * @param[in] filename Full log filename when detecting splitpoints from silence. 1096 * @return Possible error. 1097 * 1098 * @see #mp3splt_set_path_of_split 1099 */ 1100 splt_code mp3splt_set_silence_full_log_filename(splt_state *state, const char *filename); 1101 1102 //@} 1103 1104 /** 1105 * \ingroup using_libmp3splt 1106 * @defgroup splt_callback_ Registering callback functions 1107 @{ 1108 */ 1109 1110 /** 1111 * @brief Type of the message sent to the client 1112 * 1113 * @see #mp3splt_set_message_function 1114 */ 1115 typedef enum { 1116 /** 1117 * @brief Info message 1118 */ 1119 SPLT_MESSAGE_INFO, 1120 /** 1121 * @brief Warning message 1122 */ 1123 SPLT_MESSAGE_WARNING, 1124 /** 1125 * @brief Debug message 1126 */ 1127 SPLT_MESSAGE_DEBUG 1128 } splt_message_type; 1129 1130 /** 1131 * Register callback function used to send text messages to the client. 1132 * 1133 * @param[in] state Main state. 1134 * @param[in] message_cb Callback function to be called. 1135 * @param[in] cb_data User data sent through \p message_cb. 1136 * @return Possible error. 1137 * 1138 * Parameters of the callback \p message_cb function: 1139 * 1140 * \p message Text message received.\n 1141 * \p type Type of the text message received.\n 1142 * \p cb_data The user data passed to the #mp3splt_set_message_function. 1143 * 1144 * @see #splt_message_type 1145 */ 1146 splt_code mp3splt_set_message_function(splt_state *state, 1147 void (*message_cb)(const char *message, splt_message_type type, void *cb_data), void *cb_data); 1148 1149 /** 1150 * @brief Register callback function that is called when an output file is created. 1151 * 1152 * @param[in] state Main state. 1153 * @param[in] file_cb Callback function to be called. 1154 * @param[in] cb_data User data sent through \p file_cb. 1155 * @return Possible error. 1156 * 1157 * Parameters of the callback \p file_cb function: 1158 * 1159 * \p filename Output filename that has been created.\n 1160 * \p cb_data The user data passed to the #mp3splt_set_split_filename_function. 1161 */ 1162 splt_code mp3splt_set_split_filename_function(splt_state *state, 1163 void (*file_cb)(const char *filename, void *cb_data), 1164 void *cb_data); 1165 1166 /** 1167 * @brief Register callback function that is called when #SPLT_OPT_PRETEND_TO_SPLIT is 1168 * #SPLT_TRUE. 1169 * 1170 * This callback function allows getting the bytes that would have been written. 1171 * Please note that currently the mp3 Xing header is skipped when setting the input 1172 * not seekable with #SPLT_OPT_INPUT_NOT_SEEKABLE. 1173 * 1174 * @param[in] state Main state. 1175 * @param[in] write_cb Callback function to be called. 1176 * @param[in] cb_data User data sent through \p write_cb. 1177 * @return Possible error. 1178 * 1179 * Parameters of the callback \p write_cb function: 1180 * 1181 * \p ptr Bytes that would have been written to the output file.\n 1182 * \p size Size of one element stored in \p ptr.\n 1183 * \p nmemb Number of elements to be written from \p ptr.\n 1184 * \p cb_data The user data passed to the #mp3splt_set_pretend_to_split_write_function. 1185 */ 1186 splt_code mp3splt_set_pretend_to_split_write_function(splt_state *state, 1187 void (*write_cb)(const void *ptr, size_t size, size_t nmemb, void *cb_data), 1188 void *cb_data); 1189 1190 /** 1191 * @brief Type of messages sent to the client using the callback registered with 1192 * #mp3splt_set_progress_function. 1193 */ 1194 typedef enum { 1195 /** 1196 * @brief Preparing to split a song. 1197 */ 1198 SPLT_PROGRESS_PREPARE, 1199 /** 1200 * @brief Creating the output file. 1201 */ 1202 SPLT_PROGRESS_CREATE, 1203 /** 1204 * @brief Searching for synchronisation errors - when using #SPLT_OPTION_ERROR_MODE. 1205 */ 1206 SPLT_PROGRESS_SEARCH_SYNC, 1207 /** 1208 * @brief Scanning for silence - when using #SPLT_OPTION_SILENCE_MODE, 1209 * #SPLT_OPT_AUTO_ADJUST, #mp3splt_set_silence_points or #mp3splt_set_trim_silence_points. 1210 */ 1211 SPLT_PROGRESS_SCAN_SILENCE 1212 } splt_progress_messages; 1213 1214 /** 1215 * @brief Structure containing all information needed to display a progress bar. 1216 * All members are private. 1217 * 1218 * It is passed as parameter to the callback function registered with 1219 * #mp3splt_set_progress_function. 1220 * 1221 * @see #mp3splt_progress_get_type 1222 * @see #mp3splt_progress_get_filename_shorted 1223 * @see #mp3splt_progress_get_current_split 1224 * @see #mp3splt_progress_get_max_splits 1225 * @see #mp3splt_progress_get_silence_found_tracks 1226 * @see #mp3splt_progress_get_silence_db_level 1227 * @see #mp3splt_progress_get_percent_progress 1228 */ 1229 typedef struct splt_progres splt_progress; 1230 1231 /** 1232 * @brief Register callback function called to keep track of the current progress. 1233 * 1234 * @param[in] state Main state. 1235 * @param[in] progress_cb Callback function to be called. 1236 * @param[in] cb_data User data sent through \p progress_cb. 1237 * @return Possible error. 1238 * 1239 * Parameters of the callback \p progress_cb function: 1240 * 1241 * \p p_bar Progress bar informations.\n 1242 * \p cb_data The user data passed to the #mp3splt_set_progress_function. 1243 */ 1244 splt_code mp3splt_set_progress_function(splt_state *state, 1245 void (*progress_cb)(splt_progress *p_bar, void *cb_data), void *cb_data); 1246 1247 /** 1248 * @return The type of #splt_progress_messages. 1249 */ 1250 int mp3splt_progress_get_type(const splt_progress *p_bar); 1251 1252 /** 1253 * @return The filename being processed. Result must be freed. 1254 */ 1255 char *mp3splt_progress_get_filename_shorted(const splt_progress *p_bar); 1256 1257 /** 1258 * @return The current split number. 1259 */ 1260 int mp3splt_progress_get_current_split(const splt_progress *p_bar); 1261 1262 /** 1263 * @return The total number of files to be created. 1264 */ 1265 int mp3splt_progress_get_max_splits(const splt_progress *p_bar); 1266 1267 /** 1268 * @return The number of silence spots found. 1269 */ 1270 int mp3splt_progress_get_silence_found_tracks(const splt_progress *p_bar); 1271 1272 /** 1273 * @return The audio threshold level. 1274 */ 1275 float mp3splt_progress_get_silence_db_level(const splt_progress *p_bar); 1276 1277 /** 1278 * @return The progress percentage between 0 and 1. 1279 */ 1280 float mp3splt_progress_get_percent_progress(const splt_progress *p_bar); 1281 1282 /** 1283 * @brief Register callback function that is called when looking for 1284 * silence detection. 1285 * 1286 * @param[in] state Main state. 1287 * @param[in] get_silence_cb Callback function to be called. 1288 * @param[in] user_data User data sent through \p get_silence_cb. 1289 * @return Possible error. 1290 * 1291 * Parameters of the callback \p get_silence_cb function: 1292 * 1293 * \p time Current time in hundreths of seconds.\n 1294 * \p level Current silence level.\n 1295 * \p user_data The user data passed to the #mp3splt_set_silence_level_function. 1296 */ 1297 splt_code mp3splt_set_silence_level_function(splt_state *state, 1298 void (*get_silence_cb)(long time, float level, void *user_data), 1299 void *user_data); 1300 1301 //!@} 1302 1303 /** 1304 * \ingroup using_libmp3splt 1305 * @defgroup splt_splitpoints_ Splitpoints handling 1306 @{ 1307 */ 1308 1309 /** 1310 * @brief Type of the splitpoint. 1311 * @see #mp3splt_append_splitpoint, #mp3splt_point_get_type 1312 */ 1313 typedef enum { 1314 /** 1315 * @brief Regular splitpoint. 1316 */ 1317 SPLT_SPLITPOINT, 1318 /** 1319 * @brief Splitpoint used only to end the previous segment. 1320 * Segment starting with this splitpoint will not be split. 1321 */ 1322 SPLT_SKIPPOINT, 1323 } splt_type_of_splitpoint; 1324 1325 /** 1326 * @brief Structure defining one splitpoint. 1327 * All members are private. 1328 * 1329 * @see mp3splt_append_splitpoint 1330 * @see mp3splt_get_splitpoints 1331 * @see mp3splt_erase_all_splitpoints 1332 */ 1333 typedef struct _splt_point splt_point; 1334 1335 /** 1336 * @brief Creates a new splitpoint with the \p splitpoint_value. 1337 * 1338 * By default, the splitpoint has no name and it has the type #SPLT_SPLITPOINT. 1339 * 1340 * @param[in] splitpoint_value The time of the splitpoint in hundreths of seconds. 1341 * @param[out] error Possible error; can be NULL. 1342 * @return Newly allocated point. 1343 * 1344 * @see #mp3splt_point_set_name 1345 * @see #mp3splt_point_set_type 1346 * @see #mp3splt_append_splitpoint 1347 */ 1348 splt_point *mp3splt_point_new(long splitpoint_value, splt_code *error); 1349 1350 /** 1351 * @brief Sets the name on the \p splitpoint. 1352 * 1353 * @param[in] splitpoint Splitpoint to be changed. 1354 * @param[in] name Name of the splitpoint to be set. Useful when using #SPLT_OUTPUT_CUSTOM. 1355 * @return Possible error. 1356 */ 1357 splt_code mp3splt_point_set_name(splt_point *splitpoint, const char *name); 1358 1359 /** 1360 * @brief Sets the name on the \p splitpoint. 1361 * 1362 * @param[in] splitpoint Splitpoint to be changed. 1363 * @param[in] type Type of the splitpoint. 1364 * @return Possible error. 1365 */ 1366 splt_code mp3splt_point_set_type(splt_point *splitpoint, splt_type_of_splitpoint type); 1367 1368 /** 1369 * @brief Append a new splitpoint to the \p state. 1370 * 1371 * @param[in] state Main state. 1372 * @param[in] splitpoint Splitpoint to be appended; splitpoint is freed afterwards. 1373 * @return Possible error. 1374 * 1375 * @see #mp3splt_point_new 1376 */ 1377 splt_code mp3splt_append_splitpoint(splt_state *state, splt_point *splitpoint); 1378 1379 /** 1380 * @brief Structure containing several #splt_point. 1381 * All members are private. 1382 * 1383 * @see #mp3splt_points_init_iterator 1384 * @see #mp3splt_points_next 1385 */ 1386 typedef struct _splt_points splt_points; 1387 1388 /** 1389 * @brief Returns all the splitpoints of the \p state. 1390 * 1391 * @param[in] state Main state. 1392 * @param[out] error Possible error; can be NULL. 1393 * @return The splitpoints from the \p state. 1394 * 1395 * @see #mp3splt_points_init_iterator 1396 * @see #mp3splt_points_next 1397 */ 1398 splt_points *mp3splt_get_splitpoints(splt_state *state, splt_code *error); 1399 1400 /** 1401 * @brief Initialisation of the iterator for use with #mp3splt_points_next. 1402 * 1403 * @param[in] splitpoints Splitpoints returned with #mp3splt_get_splitpoints. 1404 * 1405 * @see #mp3splt_points_next 1406 */ 1407 void mp3splt_points_init_iterator(splt_points *splitpoints); 1408 1409 /** 1410 * @brief Returns the next splitpoint from the \p splitpoints. 1411 * 1412 * @param[in] splitpoints Splitpoints to be processed. 1413 * @return Next splitpoint of \p splitpoints or NULL if none found or no point remains. 1414 * 1415 * @see #mp3splt_point_get_value 1416 * @see #mp3splt_point_get_type 1417 * @see #mp3splt_point_get_name 1418 */ 1419 const splt_point *mp3splt_points_next(splt_points *splitpoints); 1420 1421 /** 1422 * @brief Returns the time value of the splitpoint \p point. 1423 * 1424 * @param[in] point Splitpoint to be queried. 1425 * @return The time value of the splitpoint. 1426 * 1427 * @see #mp3splt_get_splitpoints 1428 */ 1429 long mp3splt_point_get_value(const splt_point *point); 1430 1431 /** 1432 * @brief Returns the type of the splitpoint \p point. 1433 * Type can be #splt_type_of_splitpoint. 1434 * 1435 * @param[in] point Splitpoint to be queried. 1436 * @return The type of the requested splitpoint. 1437 * 1438 * @see #mp3splt_get_splitpoints 1439 */ 1440 splt_type_of_splitpoint mp3splt_point_get_type(const splt_point *point); 1441 1442 /** 1443 * @brief Returns the name of the splitpoint \p point. 1444 * 1445 * @param[in] point Splitpoint to be queried. 1446 * @return The name of the requested splitpoint. Result must be freed. 1447 * 1448 * @see #mp3splt_get_splitpoints 1449 */ 1450 char *mp3splt_point_get_name(const splt_point *point); 1451 1452 /** 1453 * @brief Erase all splitpoints from the \p state. 1454 * 1455 * @param[in] state Main state. 1456 * @return Possible error. 1457 */ 1458 splt_code mp3splt_erase_all_splitpoints(splt_state *state); 1459 1460 //@} 1461 1462 /** 1463 * \ingroup using_libmp3splt 1464 * @defgroup splt_tags_ Tags handling 1465 @{ 1466 */ 1467 1468 /** 1469 * @brief Undefined genre string. 1470 */ 1471 #define SPLT_UNDEFINED_GENRE "Other" 1472 1473 /** 1474 * @brief Number of ID3v1 genres. 1475 * @see #splt_id3v1_genres 1476 */ 1477 #define SPLT_ID3V1_NUMBER_OF_GENRES 127 1478 1479 /** 1480 * @brief ID3v1 genres. 1481 */ 1482 extern const char splt_id3v1_genres[SPLT_ID3V1_NUMBER_OF_GENRES][25]; 1483 1484 /** 1485 * @brief Key tags useful with #mp3splt_append_tags. 1486 */ 1487 typedef enum { 1488 SPLT_TAGS_TITLE = 1, 1489 SPLT_TAGS_ARTIST = 2, 1490 SPLT_TAGS_ALBUM = 3, 1491 SPLT_TAGS_YEAR = 4, 1492 SPLT_TAGS_COMMENT = 5, 1493 SPLT_TAGS_TRACK = 6, 1494 SPLT_TAGS_GENRE = 7, 1495 SPLT_TAGS_PERFORMER = 8, 1496 /** 1497 * @brief Use this to set original tags. 1498 * You must call #mp3splt_read_original_tags in order to use this. 1499 */ 1500 SPLT_TAGS_ORIGINAL = 900 1501 } splt_tag_key; 1502 1503 /** 1504 * @brief Structure containing the tags for one output file. 1505 * All members are private. 1506 * 1507 * The structure contains the tags that we can set to one generated file. 1508 * Tags may also define the output filenames. 1509 * 1510 * @see mp3splt_tags_set 1511 */ 1512 typedef struct _splt_tags splt_tags; 1513 1514 /** 1515 * @brief Creates a new tags structure. 1516 * 1517 * @param[in] error Possible error; can be NULL. 1518 * @return Newly allocated tags. 1519 * 1520 * @see #mp3splt_tags_set 1521 * @see #mp3splt_append_tags 1522 */ 1523 splt_tags *mp3splt_tags_new(splt_code *error); 1524 1525 /** 1526 * @brief Set tags values in the \p tags. 1527 * 1528 * The ... parameters are pairs of (key, value); arguments must end with 0, where key is a #splt_tag_key 1529 * and value is const char *. 1530 * 1531 * Example: 1532 * \code{.c} 1533 * mp3splt_tags_set(tags, SPLT_TAGS_ARTIST, "my_artist", SPLT_TAGS_ALBUM, "my_album", 0); 1534 * \endcode 1535 * 1536 * When using #SPLT_TAGS_ORIGINAL, the only possible values are "true" or "false". 1537 * In order to use #SPLT_TAGS_ORIGINAL, you have to call #mp3splt_read_original_tags before. 1538 * 1539 * @param[in] tags Tags to be changed. 1540 * @return Possible error. 1541 * 1542 * @see #mp3splt_append_tags 1543 */ 1544 splt_code mp3splt_tags_set(splt_tags *tags, ...); 1545 1546 /** 1547 * @brief Append the \p tags in the \p state. 1548 * 1549 * Tags must be appended in the same order as the splitpoints. 1550 * 1551 * First appended tags are mapped to the segment between the first two splitpoints. 1552 * Second appended tags are mapped to the second segment between the second and third splitpoints. 1553 * 1554 * @param[in] state Main state. 1555 * @param[in] tags Tags to be appended to the \p state. 1556 * @return Possible error. 1557 */ 1558 splt_code mp3splt_append_tags(splt_state *state, splt_tags *tags); 1559 1560 /** 1561 * @brief Structure containing a group of tags. 1562 * All members are private. 1563 */ 1564 typedef struct _splt_tags_group splt_tags_group; 1565 1566 /** 1567 * @brief Returns all the tags of the \p state. 1568 * 1569 * @param[in] state Main state. 1570 * @param[out] error Possible error; can be NULL. 1571 * @return The tags group of the \p state. 1572 * 1573 * @see #mp3splt_tags_group_init_iterator 1574 * @see #mp3splt_tags_group_next 1575 */ 1576 splt_tags_group *mp3splt_get_tags_group(splt_state *state, splt_code *error); 1577 1578 /** 1579 * @brief Removes all the tags of the \p state for the skippoints. 1580 * 1581 * @param[in] state Main state. 1582 * @return Possible error. 1583 */ 1584 splt_code mp3splt_remove_tags_of_skippoints(splt_state *state); 1585 1586 /** 1587 * @brief Initialisation of the iterator for use with #mp3splt_tags_group_next. 1588 * 1589 * @param[in] tags_group Group of tags returned with #mp3splt_get_tags_group. 1590 * 1591 * @see #mp3splt_tags_group_next 1592 */ 1593 void mp3splt_tags_group_init_iterator(splt_tags_group *tags_group); 1594 1595 /** 1596 * @brief Returns the next tags from the \p tags_group. 1597 * 1598 * @param[in] tags_group Tags group to be processed. 1599 * @return Next tags of \p tags_group or NULL if none found or no tags remains. 1600 * 1601 * @see #mp3splt_tags_get 1602 */ 1603 splt_tags *mp3splt_tags_group_next(splt_tags_group *tags_group); 1604 1605 /** 1606 * @brief Returns the value of \p key from the \p tags. Result must be freed. 1607 */ 1608 char *mp3splt_tags_get(splt_tags *tags, splt_tag_key key); 1609 1610 /** 1611 * @brief Fill the \p state with tags parsed from the \p tags string. 1612 * 1613 * \p tags should contain one or more square brackets pairs []. 1614 * The tags defined in the first pair of square brackets will be set on the first split file. 1615 * Those defined in the second pair of square brackets will be set on the second split file, ... 1616 * Inside a pair of square brackets, each tag is defined as \@variable=value and they tags are 1617 * separated by commas. If a percent sign % is found before the open square bracket character, 1618 * then the pair of square brackets following the % character will define the default tags in 1619 * the following files. Multiple '%' can be defined. 1620 * An optional 'r' character can be placed at the start, to replace tags in tags. 1621 * The 'replace tags in tags' option is not recursive. 1622 * 1623 * Variables can be: \@a - artist, \@b - album, \@t - title, \@y - year, \@c - comment, \@g - genre, 1624 * \@n - track number, \@o - set original tags, \@N - auto increment track number. 1625 * Variables for the start splitpoint: \@m - minutes, \@s - seconds, \@h - hundreths of seconds. 1626 * Variables for the end splitpoint: \@M - minutes, \@S - seconds, \@H - hundreths of seconds. 1627 * 1628 * Using the 'replace tags in tags' option, you can also use the following variables, which are 1629 * replaced by the data from the original tags: \#a, \#b, \#t, \#y, \#c, \#g. 1630 * Note that this will only work if \@o has been found before. 1631 * 1632 * @param[in] state Main state. 1633 * @param[in] tags String containing tags to be parsed and appended. 1634 * @param[out] error Possible error; can be NULL. 1635 * @return #SPLT_TRUE if the input tags are ambiguous. 1636 * Tags might be ambiguous if the input does not seem to be valid or if \@t or \@n is missing. 1637 */ 1638 int mp3splt_put_tags_from_string(splt_state *state, const char *tags, splt_code *error); 1639 1640 /** 1641 * @brief Parses the original tags from the input file and stores them for the future split. 1642 * 1643 * This function must be called when using #SPLT_TAGS_ORIGINAL called by #mp3splt_tags_set. 1644 * 1645 * @param[in] state Main state. 1646 * @return Possible error. 1647 */ 1648 splt_code mp3splt_read_original_tags(splt_state *state); 1649 1650 /** 1651 * @brief Erase all the tags from the \p state. 1652 * 1653 * @param[in] state Main state. 1654 * @return Possible error. 1655 */ 1656 splt_code mp3splt_erase_all_tags(splt_state *state); 1657 1658 /** 1659 * @brief Defines the regex that will be used for #SPLT_TAGS_FROM_FILENAME_REGEX. 1660 * 1661 * Tags will be extracted using the following variables: 1662 * (?\<artist>), (?\<album>), (?\<title>), (?\<tracknum>), (?\<year>), (?\<comment>), (?\<genre>). 1663 * 1664 * Example: (?\<artist>.*?) _ (?\<album>.*?) will extract 1665 * 'one artist' and 'one album' from 'one artist _ one album'. 1666 * 1667 * @param[in] state Main state. 1668 * @param[in] regex Regular expression used to set the tags from the filename. 1669 * @return Possible error. 1670 */ 1671 splt_code mp3splt_set_input_filename_regex(splt_state *state, const char *regex); 1672 1673 /** 1674 * @brief Default comment tag when using #SPLT_TAGS_FROM_FILENAME_REGEX and no comment found. 1675 * 1676 * @param[in] state Main state. 1677 * @param[in] default_comment_tag Default comment if no comment has been found. 1678 * @return Possible error. 1679 * 1680 * @see #mp3splt_set_input_filename_regex 1681 */ 1682 splt_code mp3splt_set_default_comment_tag(splt_state *state, const char *default_comment_tag); 1683 1684 /** 1685 * @brief Default genre tag when using #SPLT_TAGS_FROM_FILENAME_REGEX and no genre found. 1686 * 1687 * @param[in] state Main state. 1688 * @param[in] default_genre_tag Default genre if no genre has been found. 1689 * @return Possible error. 1690 * 1691 * @see #mp3splt_set_input_filename_regex 1692 */ 1693 splt_code mp3splt_set_default_genre_tag(splt_state *state, const char *default_genre_tag); 1694 1695 /** 1696 * @brief Parse the filename provided with #mp3splt_set_filename_to_split using regex 1697 * provided by #mp3splt_set_input_filename_regex and returns the parsed tags. 1698 * 1699 * @param[in] state Main state. 1700 * @param[out] error Possible error; can be NULL. 1701 * @return Parsed tags; must be freed with #mp3splt_free_one_tag. 1702 * 1703 * @see #mp3splt_set_filename_to_split 1704 * @see #mp3splt_set_input_filename_regex 1705 * @see #mp3splt_free_one_tag 1706 */ 1707 splt_tags *mp3splt_parse_filename_regex(splt_state *state, splt_code *error); 1708 1709 /** 1710 * @brief Free the memory of one #splt_tags 1711 * 1712 * @param[in] tags Pointer to a #splt_tags. 1713 * 1714 * @see #mp3splt_parse_filename_regex 1715 */ 1716 void mp3splt_free_one_tag(splt_tags *tags); 1717 1718 //@} 1719 1720 /** 1721 * \ingroup using_libmp3splt 1722 * @defgroup splt_split_ Split functions 1723 @{ 1724 */ 1725 1726 /** 1727 * @brief Executes the main split process. 1728 * 1729 * @param[in] state Main state. 1730 * @return Possible error. 1731 * 1732 * @see #mp3splt_stop_split 1733 * @see #mp3splt_new_state 1734 * @see #mp3splt_set_filename_to_split 1735 * @see #splt_options 1736 * @see #mp3splt_set_path_of_split 1737 */ 1738 splt_code mp3splt_split(splt_state *state); 1739 1740 /** 1741 * @brief Stop the main split process. 1742 * 1743 * @param[in] state Main state. 1744 * @return Possible error. 1745 * 1746 * @see #mp3splt_split 1747 */ 1748 splt_code mp3splt_stop_split(splt_state *state); 1749 1750 /** 1751 * @brief Recursive search of all the filenames matching the loaded plugins. 1752 * 1753 * @param[in] state Main state. 1754 * @param[in] filename Directory to be looked for recursive search. 1755 * @param[out] num_of_files_found Number of files found. 1756 * @param[out] error Possible error; can be NULL. 1757 * @return Newly allocated array of found files that must be freed. 1758 * 1759 * @see #mp3splt_set_filename_to_split and #mp3splt_split 1760 */ 1761 char **mp3splt_find_filenames(splt_state *state, const char *filename, 1762 int *num_of_files_found, splt_code *error); 1763 1764 //@} 1765 1766 /** 1767 * \ingroup using_libmp3splt 1768 * @defgroup splt_import_ Import splitpoints 1769 @{ 1770 */ 1771 1772 /** 1773 * @brief Type of the import. 1774 * 1775 * @see #mp3splt_import 1776 */ 1777 typedef enum { 1778 CUE_IMPORT, 1779 CDDB_IMPORT, 1780 AUDACITY_LABELS_IMPORT, 1781 PLUGIN_INTERNAL_IMPORT 1782 } splt_import_type; 1783 1784 /** 1785 * @brief Import splitpoints from the \p file having the \p type into the \p state. 1786 * 1787 * @param[in] state Main state. 1788 * @param[in] type Type of the import. 1789 * @param[in] file File to import. 1790 * @return Possible error. 1791 * 1792 * @see #mp3splt_split 1793 */ 1794 splt_code mp3splt_import(splt_state *state, splt_import_type type, const char *file); 1795 1796 /** 1797 * @brief Search CDDB file using CDDB CGI protocol (tracktype.org). 1798 * 1799 * @see #mp3splt_get_freedb_search 1800 */ 1801 #define SPLT_FREEDB_SEARCH_TYPE_CDDB_CGI 1 1802 1803 /** 1804 * @brief Get CDDB file using CDDB CGI protocol (tracktype.org or freedb.org). 1805 * 1806 * @see #mp3splt_write_freedb_file_result 1807 */ 1808 #define SPLT_FREEDB_GET_FILE_TYPE_CDDB_CGI 3 1809 1810 /** 1811 * @brief Get CDDB file using freedb.org CDDB protocol. 1812 * 1813 * @see #mp3splt_write_freedb_file_result 1814 */ 1815 #define SPLT_FREEDB_GET_FILE_TYPE_CDDB 4 1816 1817 /** 1818 * @brief Default port. 1819 * 1820 * @see #mp3splt_get_freedb_search 1821 * @see #mp3splt_write_freedb_file_result 1822 */ 1823 #define SPLT_FREEDB_CDDB_CGI_PORT 80 1824 1825 /** 1826 * @brief URL of tracktype.org when using #SPLT_FREEDB_SEARCH_TYPE_CDDB_CGI and 1827 * #SPLT_FREEDB_GET_FILE_TYPE_CDDB_CGI types. 1828 * 1829 * @see #mp3splt_get_freedb_search 1830 * @see #mp3splt_write_freedb_file_result 1831 */ 1832 #define SPLT_FREEDB2_CGI_SITE "tracktype.org/~cddb/cddb.cgi" 1833 1834 /** 1835 * @brief Structure containing the freedb search results. 1836 * All members are private. 1837 * 1838 * @see mp3splt_get_freedb_search 1839 * @see #mp3splt_freedb_init_iterator 1840 * @see #mp3splt_freedb_next 1841 */ 1842 typedef struct _splt_freedb_results splt_freedb_results; 1843 1844 /** 1845 * @brief Structure containing only one freedb result. 1846 * 1847 * @see #mp3splt_freedb_get_id 1848 * @see #mp3splt_freedb_get_name 1849 * @see #mp3splt_freedb_get_number_of_revisions 1850 */ 1851 typedef struct _splt_freedb_one_result splt_freedb_one_result; 1852 1853 /** 1854 * @brief Use proxy when accessing the internet. 1855 * 1856 * @param[in] state Main state. 1857 * @param[in] proxy_address Proxy address. 1858 * @param[in] proxy_port Port of the \p proxy_address. 1859 * @return Possible error. 1860 */ 1861 splt_code mp3splt_use_proxy(splt_state *state, const char *proxy_address, int proxy_port); 1862 1863 /** 1864 * @brief Use proxy with base64 authentification. 1865 * 1866 * @param[in] state Main state. 1867 * @param[in] base64_authentification Authentification credentials encoded in base64. 1868 * @return Possible error. 1869 * 1870 * @see #mp3splt_encode_in_base64 1871 * @see #mp3splt_clear_proxy 1872 * @see #mp3splt_use_proxy 1873 */ 1874 splt_code mp3splt_use_base64_authentification(splt_state *state, 1875 const char *base64_authentification); 1876 1877 /** 1878 * @brief Encode the \p input in base64. 1879 * 1880 * @param[in] state Main state. 1881 * @param[in] input Input to be encoded in base64. 1882 * @param[in] error Possible error; can be NULL. 1883 * @return The \p input encoded as base64. 1884 * 1885 * @see #mp3splt_use_base64_authentification 1886 */ 1887 char *mp3splt_encode_in_base64(splt_state *state, const char *input, int *error); 1888 1889 /** 1890 * @brief Clears the proxy data from the \p state. 1891 * For security purposes, use this function as soon as the proxy is not needed any more. 1892 * 1893 * @param[in] state Main state. 1894 */ 1895 void mp3splt_clear_proxy(splt_state *state); 1896 1897 /** 1898 * @brief Search on the internet for the \p searched_string and returns the results. 1899 * 1900 * @param[in] state Main state. 1901 * @param[in] searched_string Search string - might be artist or album. 1902 * @param[out] error Possible error; can be NULL. 1903 * @param[in] search_type Type of the search. 1904 * Only #SPLT_FREEDB_SEARCH_TYPE_CDDB_CGI is supported for the moment. 1905 * @param[in] search_server You can use #SPLT_FREEDB2_CGI_SITE as search server. 1906 * @param[in] port Port of the \p search_server. Can be #SPLT_FREEDB_CDDB_CGI_PORT. 1907 * @return The search results. 1908 * 1909 * @see #mp3splt_freedb_init_iterator 1910 * @see #mp3splt_freedb_next 1911 * @see #mp3splt_write_freedb_file_result 1912 */ 1913 splt_freedb_results *mp3splt_get_freedb_search(splt_state *state, 1914 const char *searched_string, splt_code *error, 1915 int search_type, const char *search_server, int port); 1916 1917 /** 1918 * @brief Initialisation of the iterator for use with #mp3splt_freedb_next 1919 * 1920 * @param[in] freedb_results Freedb results returned with #mp3splt_get_freedb_search. 1921 * 1922 * @see #mp3splt_freedb_next 1923 */ 1924 void mp3splt_freedb_init_iterator(splt_freedb_results *freedb_results); 1925 1926 /** 1927 * @brief Returns the next freedb result from the \p freedb_results. 1928 * 1929 * @param[in] freedb_results Freedb results to be processed. 1930 * @return Next freedb result of \p freedb_results or NULL if none found or no result remains. 1931 * 1932 * @see #mp3splt_freedb_get_id 1933 * @see #mp3splt_freedb_get_name 1934 * @see #mp3splt_freedb_get_number_of_revisions 1935 */ 1936 const splt_freedb_one_result *mp3splt_freedb_next(splt_freedb_results *freedb_results); 1937 1938 /** 1939 * @brief Returns the ID of the \p result. 1940 * The ID is needed when using #mp3splt_write_freedb_file_result. 1941 */ 1942 int mp3splt_freedb_get_id(const splt_freedb_one_result *result); 1943 1944 /** 1945 * @brief Returns the name of the \p result. 1946 */ 1947 const char *mp3splt_freedb_get_name(const splt_freedb_one_result *result); 1948 1949 /** 1950 * @brief Returns the number of revisions of the \p result. 1951 */ 1952 int mp3splt_freedb_get_number_of_revisions(const splt_freedb_one_result *result); 1953 1954 /** 1955 * @brief Downloads the CDDB file of the \p disc_id and writes it to a file. 1956 * 1957 * @param[in] state Main state. 1958 * @param[in] disc_id ID of the chosen disc provided by #mp3splt_freedb_get_id. 1959 * @param[in] output_file Name of the output CDDB file that will be written. 1960 * @param[in] cddb_get_type Type of the download. 1961 * Can be #SPLT_FREEDB_GET_FILE_TYPE_CDDB or #SPLT_FREEDB_GET_FILE_TYPE_CDDB_CGI. 1962 * @param[in] cddb_get_server Name of the server from the file is downloaded. 1963 * Can be #SPLT_FREEDB2_CGI_SITE (or freedb.org or freedb.org/~cddb/cddb.cgi). 1964 * @param[in] port Port of the \p cddb_get_server. 1965 * Can be #SPLT_FREEDB_CDDB_CGI_PORT (or 8880) for example. 1966 * @return Possible error. 1967 * 1968 * @see #mp3splt_get_freedb_search 1969 */ 1970 splt_code mp3splt_write_freedb_file_result(splt_state *state, 1971 int disc_id, const char *output_file, 1972 int cddb_get_type, const char *cddb_get_server, int port); 1973 1974 //@} 1975 1976 /** 1977 * \ingroup using_libmp3splt 1978 * @defgroup splt_export_ Export splitpoints 1979 @{ 1980 */ 1981 1982 /** 1983 * @brief Type of the export. 1984 * 1985 * @see #mp3splt_export 1986 */ 1987 typedef enum { 1988 CUE_EXPORT 1989 } splt_export_type; 1990 1991 /** 1992 * @brief Export splitpoints from the \p state into the \p file saved as \p type. 1993 * 1994 * @param[in] state Main state. 1995 * @param[in] type Export type. 1996 * @param[in] file File to be written with splitpoints from the \p state. 1997 * @param[in] stop_at_total_time If #SPLT_TRUE, don't export splitpoints after the total time 1998 * of the input file. 1999 * @return Possible error. 2000 */ 2001 splt_code mp3splt_export(splt_state *state, splt_export_type type, 2002 const char *file, int stop_at_total_time); 2003 2004 //@} 2005 2006 /** 2007 * \ingroup using_libmp3splt 2008 * @defgroup splt_wrap_ Wrap utilities 2009 @{ 2010 */ 2011 2012 /** 2013 * @brief Structure containg the wrapped filenames found inside the input filename. 2014 * All members are private. 2015 * 2016 * @see #mp3splt_get_wrap_files 2017 * @see #mp3splt_wrap_init_iterator 2018 * @see #mp3splt_wrap_next 2019 */ 2020 typedef struct _splt_wrap splt_wrap; 2021 2022 /** 2023 * @brief Structure containing one wrapped file 2024 * All members are private 2025 * 2026 * @see #mp3splt_wrap_get_wrapped_file 2027 */ 2028 typedef struct _splt_one_wrap splt_one_wrap; 2029 2030 /** 2031 * @brief Returns the wrapped files found from the input filename set with 2032 * #mp3splt_set_filename_to_split. 2033 * 2034 * @param[in] state Main state. 2035 * @param[out] error Possible error; can be NULL. 2036 * @return Wrapped files found. 2037 * 2038 * @see #mp3splt_wrap_init_iterator 2039 * @see #mp3splt_wrap_next 2040 */ 2041 splt_wrap *mp3splt_get_wrap_files(splt_state *state, splt_code *error); 2042 2043 /** 2044 * @brief Initialisation of the iterator for use with #mp3splt_wrap_next. 2045 * 2046 * @param[in] wrap Wrapped files returned with #mp3splt_get_wrap_files. 2047 * 2048 * @see #mp3splt_wrap_next 2049 */ 2050 void mp3splt_wrap_init_iterator(splt_wrap *wrap); 2051 2052 /** 2053 * @brief Returns the next wrapped file from the \p wrap. 2054 * 2055 * @param[in] wrap Wrapped files to be processed. 2056 * @return Next wrapped file of \p wrap or NULL if none found or no wrapped file remains. 2057 * 2058 * @see #mp3splt_wrap_get_wrapped_file 2059 */ 2060 const splt_one_wrap *mp3splt_wrap_next(splt_wrap *wrap); 2061 2062 /** 2063 * @brief Returns the wrapped file from \p one_wrap. Result must be freed. 2064 */ 2065 char *mp3splt_wrap_get_wrapped_file(const splt_one_wrap *one_wrap); 2066 2067 //@} 2068 2069 /** 2070 * \ingroup using_libmp3splt 2071 * @defgroup splt_other_ Other utilities 2072 @{ 2073 */ 2074 2075 /** 2076 * @brief Scan for silence and set silence splitpoints in the \p state. 2077 * 2078 * @param[in] state Main state. 2079 * @param[out] error Possible error; can be NULL. 2080 * @return The number of silence spots found. 2081 */ 2082 int mp3splt_set_silence_points(splt_state *state, splt_code *error); 2083 2084 /** 2085 * @brief Scan for silence and set silence trim splitpoints in the \p state. 2086 * 2087 * @param[in] state Main state. 2088 * @return Possible error. 2089 */ 2090 splt_code mp3splt_set_trim_silence_points(splt_state *state); 2091 2092 /** 2093 * @brief Returns the version of libmp3splt. Result must be freed. 2094 */ 2095 char *mp3splt_get_version(); 2096 2097 #ifdef __WIN32__ 2098 /** 2099 * @brief Returns \p source converted from UTF-16 to UTF-8. 2100 */ 2101 char *mp3splt_win32_utf16_to_utf8(const wchar_t *source); 2102 #endif 2103 2104 /** 2105 * @brief Returns #SPLT_TRUE if \p filename is a directory. 2106 */ 2107 int mp3splt_check_if_directory(const char *filename); 2108 2109 #ifndef SPLT_DIRCHAR 2110 #ifdef __WIN32__ 2111 #define SPLT_DIRCHAR '\\' 2112 #define SPLT_DIRSTR "\\" 2113 #else 2114 /** 2115 * @brief Path separator as character (/ or \\) 2116 */ 2117 #define SPLT_DIRCHAR '/' 2118 /** 2119 * @brief Path separator as string (/ or \\) 2120 */ 2121 #define SPLT_DIRSTR "/" 2122 #endif 2123 #endif 2124 2125 //@} 2126 2127 /** @defgroup splt_plugin_api Creating libmp3splt plugins 2128 * See #splt_plugin_func for detailed description. 2129 @{ 2130 */ 2131 2132 /** 2133 * @brief Structure containing plugin information, like the version, the name and file extension. 2134 */ 2135 typedef struct { 2136 /** 2137 * @brief Plugin version. 2138 */ 2139 float version; 2140 /** 2141 * @brief Plugin name. 2142 */ 2143 char *name; 2144 /** 2145 * @brief File extension handled by the plugin 2146 */ 2147 char *extension; 2148 /** 2149 * @brief File extension handled by the plugin as uppercase. 2150 */ 2151 char *upper_extension; 2152 } splt_plugin_info; 2153 2154 /** 2155 * @brief Structure containing the original tags of the input file. 2156 */ 2157 typedef struct _splt_original_tags splt_original_tags; 2158 2159 /** 2160 * @brief Libmp3splt plugin API. 2161 * 2162 * \warning The plugin API might still change. 2163 * 2164 * In order to create a plugin for libmp3splt, the following functions can be implemented.\n 2165 * Mandatory functions are #splt_pl_init, #splt_pl_end, #splt_pl_check_plugin_is_for_file, 2166 * #splt_pl_set_plugin_info and #splt_pl_split. 2167 * 2168 * Examples can be found for the <a 2169 * href="http://svn.code.sf.net/p/mp3splt/code/mp3splt-project/trunk/libmp3splt/plugins/mp3.c">mp3</a>, 2170 * <a href="http://svn.code.sf.net/p/mp3splt/code/mp3splt-project/trunk/libmp3splt/plugins/ogg.c">ogg vorbis</a> 2171 * <a href="http://svn.code.sf.net/p/mp3splt/code/mp3splt-project/trunk/libmp3splt/plugins/flac.c">FLAC</a> 2172 * implementations. 2173 */ 2174 typedef struct { 2175 /** 2176 * @brief Initialise the plugin. Mandatory. 2177 * 2178 * Create the plugin data, open the input file and read headers.\n 2179 * Use the \p state->codec pointer to store the plugin data. 2180 * 2181 * @param[in] state Main state. 2182 * @param[out] error Fill in possible error. 2183 */ 2184 void (*splt_pl_init)(splt_state *state, splt_code *error); 2185 /** 2186 * @brief Unitialise the plugin. Mandatory. 2187 * 2188 * Close the input file, free the plugin data.\n 2189 * 2190 * @param[in] state Main state. 2191 * @param[out] error Fill in possible error. 2192 */ 2193 void (*splt_pl_end)(splt_state *state, splt_code *error); 2194 /** 2195 * @brief Checks if the plugin matches the input file. Mandatory. 2196 * 2197 * If stdin is supported, don't forget to check if the input filename is stdin. 2198 * 2199 * @param[in] state Main state. 2200 * @param[out] error Fill in possible error. 2201 * @return #SPLT_TRUE if the plugin matches the input file. 2202 */ 2203 int (*splt_pl_check_plugin_is_for_file)(splt_state *state, splt_code *error); 2204 /** 2205 * @brief Set plugin information into the \p information structure. Mandatory. 2206 * 2207 * Information like the plugin version, plugin name and file extension must be filled.\n 2208 * 2209 * @param[in] splt_plugin_info Plugin information to be filled. Parameter is already allocated. 2210 * @param[out] error Fill in possible error. 2211 */ 2212 void (*splt_pl_set_plugin_info)(splt_plugin_info *information, splt_code *error); 2213 /** 2214 * @brief Main split function. Mandatory. 2215 * 2216 * @param[in] state Main state. 2217 * @param[in] final_fname Output filename to be written for this split. 2218 * @param[in] begin_point Begin point where the split starts as seconds.hundreths. 2219 * @param[in] end_point End point where the split ends as seconds.hundreths. 2220 * @param[out] error Fill in possible error. 2221 * @param[in] save_end_point Is equal to #SPLT_TRUE if optimisation can be done for saving the 2222 * end point seek for the next call to this function. This avoids looking for the next begin point 2223 * seek since it will be equal to the previous saved end point seek. 2224 * @return The real end point split; in most cases, it is equal to the \p end_point. 2225 */ 2226 double (*splt_pl_split)(splt_state *state, const char *final_fname, double begin_point, 2227 double end_point, splt_code *error, int save_end_point); 2228 /** 2229 * @brief Set the original tags into the \p state from the input file. 2230 * 2231 * \p splt_tu_set_original_tags_field has to be used to set the original tags.\n 2232 * You can also save all the original tags in the \p state using \p 2233 * splt_tu_set_original_tags_data, in case you want to write them all in the output file, 2234 * for the tags that are not supported by the library's structure. 2235 * 2236 * @param[in] state Main state. 2237 * @param[out] error Fill in possible error. 2238 */ 2239 void (*splt_pl_set_original_tags)(splt_state *state, splt_code *error); 2240 /** 2241 * @brief Frees the memory of the tags previously set in the #splt_pl_set_original_tags function. 2242 * 2243 * Free the \p original_tags->all_original_tags data previously set with 2244 * \p splt_tu_set_original_tags_data. 2245 * 2246 * @param[in] original_tags Original tags structure containing the original tags data to be freed. 2247 */ 2248 void (*splt_pl_clear_original_tags)(splt_original_tags *original_tags); 2249 /** 2250 * @brief Scan the input file for silence. 2251 * 2252 * The input file has to be scanned for silence and for each time/audio level, a generic silence 2253 * processor will be called.\n 2254 * The processor handles the mp3splt silence detection logic. 2255 * 2256 * @param[in] state Main state. 2257 * @param[out] error Fill in possible error. 2258 * @return The number of silence spots found. 2259 */ 2260 int (*splt_pl_scan_silence)(splt_state *state, splt_code *error); 2261 /** 2262 * @brief Scan the input file for trimming using silence detection. 2263 * 2264 * The implementation of this function is straight forward after implementing 2265 * #splt_pl_scan_silence, since the silence detection is the same.\n 2266 * Only the generic silence processor changes. 2267 * 2268 * @param[in] state Main state. 2269 * @param[out] error Fill in possible error. 2270 * @return The number of silence spots found. 2271 */ 2272 int (*splt_pl_scan_trim_silence)(splt_state *state, splt_code *error); 2273 /** 2274 * @brief Search for synchronisation errors. 2275 * 2276 * Currently only mp3 supports synchronisation errors split. 2277 * 2278 * @param[in] state Main state. 2279 * @param[out] error Fill in possible error. 2280 */ 2281 void (*splt_pl_search_syncerrors)(splt_state *state, splt_code *error); 2282 /** 2283 * @brief Split the input filename by offsets. 2284 * 2285 * Currently only used when splitting mp3 files using the synchronisation error mode. 2286 * 2287 * @param[in] state Main state. 2288 * @param[in] output_fname Output filename. 2289 * @param[in] begin Begin offset of the portion to be split. 2290 * @param[in] end End offset of the portion to be split. 2291 * @return Possible error. 2292 */ 2293 int (*splt_pl_offset_split)(splt_state *state, const char *output_fname, off_t begin, off_t end); 2294 /** 2295 * @brief Unwrap the input file into the directory \p dir. 2296 * 2297 * Currently only mp3 supports wrapped files. 2298 * 2299 * @param[in] state Main state. 2300 * @param[in] listonly If equal to #SPLT_TRUE, then the wrapped files found are stored in the \p 2301 * state without actually splitting. 2302 * @param[in] dir Output directory where the wrapped files have to be stored. 2303 * @param[out] error Fill in possible error. 2304 */ 2305 void (*splt_pl_dewrap)(splt_state *state, int listonly, const char *dir, splt_code *error); 2306 /** 2307 * @brief Import splitpoints from internal sheets. 2308 * 2309 * @param[in] state Main state. 2310 * @param[out] error Fill in possible error. 2311 */ 2312 void (*splt_pl_import_internal_sheets)(splt_state *state, splt_code *error); 2313 } splt_plugin_func; 2314 2315 //@} 2316 2317 /** 2318 * @brief Allow several inclusions of this file. 2319 */ 2320 #define MP3SPLT_MP3SPLT_H 2321 #endif 2322 2323