ref: 49be06378c40d1b08ec62e9451b394d7a05d9def
parent: 879b0c2409f166d355175809a1c9f9c48f4e7b55
author: Doug Cook <idigdoug@users.sourceforge.net>
date: Mon Dec 26 19:02:38 EST 2011
Add Doxygen (JavaDoc-like) comments to sox.h. Also some cleanup: changed some macros into enums, changed case on some macros, etc.
--- /dev/null
+++ b/Doxyfile
@@ -1,0 +1,1790 @@
+# Doxyfile 1.7.6.1
+
+# This file describes the settings to be used by the documentation system
+# doxygen (www.doxygen.org) for a project
+#
+# All text after a hash (#) is considered a comment and will be ignored
+# The format is:
+# TAG = value [value, ...]
+# For lists items can also be appended using:
+# TAG += value [value, ...]
+# Values that contain spaces should be placed between quotes (" ")+
+#---------------------------------------------------------------------------
+# Project related configuration options
+#---------------------------------------------------------------------------
+
+# This tag specifies the encoding used for all characters in the config file
+# that follow. The default is UTF-8 which is also the encoding used for all
+# text before the first occurrence of this tag. Doxygen uses libiconv (or the
+# iconv built into libc) for the transcoding. See
+# http://www.gnu.org/software/libiconv for the list of possible encodings.
+
+DOXYFILE_ENCODING = UTF-8
+
+# The PROJECT_NAME tag is a single word (or sequence of words) that should
+# identify the project. Note that if you do not use Doxywizard you need
+# to put quotes around the project name if it contains spaces.
+
+PROJECT_NAME = "SoX - Sound eXchange"
+
+# The PROJECT_NUMBER tag can be used to enter a project or revision number.
+# This could be handy for archiving the generated documentation or
+# if some version control system is used.
+
+PROJECT_NUMBER =
+
+# Using the PROJECT_BRIEF tag one can provide an optional one line description
+# for a project that appears at the top of each page and should give viewer
+# a quick idea about the purpose of the project. Keep the description short.
+
+PROJECT_BRIEF = "Audio file processing tool."
+
+# With the PROJECT_LOGO tag one can specify an logo or icon that is
+# included in the documentation. The maximum height of the logo should not
+# exceed 55 pixels and the maximum width should not exceed 200 pixels.
+# Doxygen will copy the logo to the output directory.
+
+PROJECT_LOGO =
+
+# The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute)
+# base path where the generated documentation will be put.
+# If a relative path is entered, it will be relative to the location
+# where doxygen was started. If left blank the current directory will be used.
+
+OUTPUT_DIRECTORY = doc
+
+# If the CREATE_SUBDIRS tag is set to YES, then doxygen will create
+# 4096 sub-directories (in 2 levels) under the output directory of each output
+# format and will distribute the generated files over these directories.
+# Enabling this option can be useful when feeding doxygen a huge amount of
+# source files, where putting all generated files in the same directory would
+# otherwise cause performance problems for the file system.
+
+CREATE_SUBDIRS = NO
+
+# The OUTPUT_LANGUAGE tag is used to specify the language in which all
+# documentation generated by doxygen is written. Doxygen will use this
+# information to generate all constant output in the proper language.
+# The default language is English, other supported languages are:
+# Afrikaans, Arabic, Brazilian, Catalan, Chinese, Chinese-Traditional,
+# Croatian, Czech, Danish, Dutch, Esperanto, Farsi, Finnish, French, German,
+# Greek, Hungarian, Italian, Japanese, Japanese-en (Japanese with English
+# messages), Korean, Korean-en, Lithuanian, Norwegian, Macedonian, Persian,
+# Polish, Portuguese, Romanian, Russian, Serbian, Serbian-Cyrillic, Slovak,
+# Slovene, Spanish, Swedish, Ukrainian, and Vietnamese.
+
+OUTPUT_LANGUAGE = English
+
+# If the BRIEF_MEMBER_DESC tag is set to YES (the default) Doxygen will
+# include brief member descriptions after the members that are listed in
+# the file and class documentation (similar to JavaDoc).
+# Set to NO to disable this.
+
+BRIEF_MEMBER_DESC = YES
+
+# If the REPEAT_BRIEF tag is set to YES (the default) Doxygen will prepend
+# the brief description of a member or function before the detailed description.
+# Note: if both HIDE_UNDOC_MEMBERS and BRIEF_MEMBER_DESC are set to NO, the
+# brief descriptions will be completely suppressed.
+
+REPEAT_BRIEF = YES
+
+# This tag implements a quasi-intelligent brief description abbreviator
+# that is used to form the text in various listings. Each string
+# in this list, if found as the leading text of the brief description, will be
+# stripped from the text and the result after processing the whole list, is
+# used as the annotated text. Otherwise, the brief description is used as-is.
+# If left blank, the following values are used ("$name" is automatically +# replaced with the name of the entity): "The $name class" "The $name widget"
+# "The $name file" "is" "provides" "specifies" "contains"
+# "represents" "a" "an" "the"
+
+ABBREVIATE_BRIEF = "The $name class" \
+ "The $name widget" \
+ "The $name file" \
+ is \
+ provides \
+ specifies \
+ contains \
+ represents \
+ a \
+ an \
+ the
+
+# If the ALWAYS_DETAILED_SEC and REPEAT_BRIEF tags are both set to YES then
+# Doxygen will generate a detailed section even if there is only a brief
+# description.
+
+ALWAYS_DETAILED_SEC = NO
+
+# If the INLINE_INHERITED_MEMB tag is set to YES, doxygen will show all
+# inherited members of a class in the documentation of that class as if those
+# members were ordinary class members. Constructors, destructors and assignment
+# operators of the base classes will not be shown.
+
+INLINE_INHERITED_MEMB = NO
+
+# If the FULL_PATH_NAMES tag is set to YES then Doxygen will prepend the full
+# path before files name in the file list and in the header files. If set
+# to NO the shortest path that makes the file name unique will be used.
+
+FULL_PATH_NAMES = YES
+
+# If the FULL_PATH_NAMES tag is set to YES then the STRIP_FROM_PATH tag
+# can be used to strip a user-defined part of the path. Stripping is
+# only done if one of the specified strings matches the left-hand part of
+# the path. The tag can be used to show relative paths in the file list.
+# If left blank the directory from which doxygen is run is used as the
+# path to strip.
+
+STRIP_FROM_PATH =
+
+# The STRIP_FROM_INC_PATH tag can be used to strip a user-defined part of
+# the path mentioned in the documentation of a class, which tells
+# the reader which header file to include in order to use a class.
+# If left blank only the name of the header file containing the class
+# definition is used. Otherwise one should specify the include paths that
+# are normally passed to the compiler using the -I flag.
+
+STRIP_FROM_INC_PATH =
+
+# If the SHORT_NAMES tag is set to YES, doxygen will generate much shorter
+# (but less readable) file names. This can be useful if your file system
+# doesn't support long names like on DOS, Mac, or CD-ROM.
+
+SHORT_NAMES = NO
+
+# If the JAVADOC_AUTOBRIEF tag is set to YES then Doxygen
+# will interpret the first line (until the first dot) of a JavaDoc-style
+# comment as the brief description. If set to NO, the JavaDoc
+# comments will behave just like regular Qt-style comments
+# (thus requiring an explicit @brief command for a brief description.)
+
+JAVADOC_AUTOBRIEF = YES
+
+# If the QT_AUTOBRIEF tag is set to YES then Doxygen will
+# interpret the first line (until the first dot) of a Qt-style
+# comment as the brief description. If set to NO, the comments
+# will behave just like regular Qt-style comments (thus requiring
+# an explicit \brief command for a brief description.)
+
+QT_AUTOBRIEF = NO
+
+# The MULTILINE_CPP_IS_BRIEF tag can be set to YES to make Doxygen
+# treat a multi-line C++ special comment block (i.e. a block of //! or ///
+# comments) as a brief description. This used to be the default behaviour.
+# The new default is to treat a multi-line C++ comment block as a detailed
+# description. Set this tag to YES if you prefer the old behaviour instead.
+
+MULTILINE_CPP_IS_BRIEF = NO
+
+# If the INHERIT_DOCS tag is set to YES (the default) then an undocumented
+# member inherits the documentation from any documented member that it
+# re-implements.
+
+INHERIT_DOCS = YES
+
+# If the SEPARATE_MEMBER_PAGES tag is set to YES, then doxygen will produce
+# a new page for each member. If set to NO, the documentation of a member will
+# be part of the file/class/namespace that contains it.
+
+SEPARATE_MEMBER_PAGES = NO
+
+# The TAB_SIZE tag can be used to set the number of spaces in a tab.
+# Doxygen uses this value to replace tabs by spaces in code fragments.
+
+TAB_SIZE = 8
+
+# This tag can be used to specify a number of aliases that acts
+# as commands in the documentation. An alias has the form "name=value".
+# For example adding "sideeffect=\par Side Effects:\n" will allow you to
+# put the command \sideeffect (or @sideeffect) in the documentation, which
+# will result in a user-defined paragraph with heading "Side Effects:".
+# You can put \n's in the value part of an alias to insert newlines.
+
+ALIASES =
+
+# This tag can be used to specify a number of word-keyword mappings (TCL only).
+# A mapping has the form "name=value". For example adding
+# "class=itcl::class" will allow you to use the command class in the
+# itcl::class meaning.
+
+TCL_SUBST =
+
+# Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C
+# sources only. Doxygen will then generate output that is more tailored for C.
+# For instance, some of the names that are used will be different. The list
+# of all members will be omitted, etc.
+
+OPTIMIZE_OUTPUT_FOR_C = NO
+
+# Set the OPTIMIZE_OUTPUT_JAVA tag to YES if your project consists of Java
+# sources only. Doxygen will then generate output that is more tailored for
+# Java. For instance, namespaces will be presented as packages, qualified
+# scopes will look different, etc.
+
+OPTIMIZE_OUTPUT_JAVA = NO
+
+# Set the OPTIMIZE_FOR_FORTRAN tag to YES if your project consists of Fortran
+# sources only. Doxygen will then generate output that is more tailored for
+# Fortran.
+
+OPTIMIZE_FOR_FORTRAN = NO
+
+# Set the OPTIMIZE_OUTPUT_VHDL tag to YES if your project consists of VHDL
+# sources. Doxygen will then generate output that is tailored for
+# VHDL.
+
+OPTIMIZE_OUTPUT_VHDL = NO
+
+# Doxygen selects the parser to use depending on the extension of the files it
+# parses. With this tag you can assign which parser to use for a given extension.
+# Doxygen has a built-in mapping, but you can override or extend it using this
+# tag. The format is ext=language, where ext is a file extension, and language
+# is one of the parsers supported by doxygen: IDL, Java, Javascript, CSharp, C,
+# C++, D, PHP, Objective-C, Python, Fortran, VHDL, C, C++. For instance to make
+# doxygen treat .inc files as Fortran files (default is PHP), and .f files as C
+# (default is Fortran), use: inc=Fortran f=C. Note that for custom extensions
+# you also need to set FILE_PATTERNS otherwise the files are not read by doxygen.
+
+EXTENSION_MAPPING =
+
+# If you use STL classes (i.e. std::string, std::vector, etc.) but do not want
+# to include (a tag file for) the STL sources as input, then you should
+# set this tag to YES in order to let doxygen match functions declarations and
+# definitions whose arguments contain STL classes (e.g. func(std::string); v.s.
+# func(std::string) {}). This also makes the inheritance and collaboration +# diagrams that involve STL classes more complete and accurate.
+
+BUILTIN_STL_SUPPORT = NO
+
+# If you use Microsoft's C++/CLI language, you should set this option to YES to
+# enable parsing support.
+
+CPP_CLI_SUPPORT = NO
+
+# Set the SIP_SUPPORT tag to YES if your project consists of sip sources only.
+# Doxygen will parse them like normal C++ but will assume all classes use public
+# instead of private inheritance when no explicit protection keyword is present.
+
+SIP_SUPPORT = NO
+
+# For Microsoft's IDL there are propget and propput attributes to indicate getter
+# and setter methods for a property. Setting this option to YES (the default)
+# will make doxygen replace the get and set methods by a property in the
+# documentation. This will only work if the methods are indeed getting or
+# setting a simple type. If this is not the case, or you want to show the
+# methods anyway, you should set this option to NO.
+
+IDL_PROPERTY_SUPPORT = YES
+
+# If member grouping is used in the documentation and the DISTRIBUTE_GROUP_DOC
+# tag is set to YES, then doxygen will reuse the documentation of the first
+# member in the group (if any) for the other members of the group. By default
+# all members of a group must be documented explicitly.
+
+DISTRIBUTE_GROUP_DOC = NO
+
+# Set the SUBGROUPING tag to YES (the default) to allow class member groups of
+# the same type (for instance a group of public functions) to be put as a
+# subgroup of that type (e.g. under the Public Functions section). Set it to
+# NO to prevent subgrouping. Alternatively, this can be done per class using
+# the \nosubgrouping command.
+
+SUBGROUPING = YES
+
+# When the INLINE_GROUPED_CLASSES tag is set to YES, classes, structs and
+# unions are shown inside the group in which they are included (e.g. using
+# @ingroup) instead of on a separate page (for HTML and Man pages) or
+# section (for LaTeX and RTF).
+
+INLINE_GROUPED_CLASSES = NO
+
+# When the INLINE_SIMPLE_STRUCTS tag is set to YES, structs, classes, and
+# unions with only public data fields will be shown inline in the documentation
+# of the scope in which they are defined (i.e. file, namespace, or group
+# documentation), provided this scope is documented. If set to NO (the default),
+# structs, classes, and unions are shown on a separate page (for HTML and Man
+# pages) or section (for LaTeX and RTF).
+
+INLINE_SIMPLE_STRUCTS = NO
+
+# When TYPEDEF_HIDES_STRUCT is enabled, a typedef of a struct, union, or enum
+# is documented as struct, union, or enum with the name of the typedef. So
+# typedef struct TypeS {} TypeT, will appear in the documentation as a struct +# with name TypeT. When disabled the typedef will appear as a member of a file,
+# namespace, or class. And the struct will be named TypeS. This can typically
+# be useful for C code in case the coding convention dictates that all compound
+# types are typedef'ed and only the typedef is referenced, never the tag name.
+
+TYPEDEF_HIDES_STRUCT = YES
+
+# The SYMBOL_CACHE_SIZE determines the size of the internal cache use to
+# determine which symbols to keep in memory and which to flush to disk.
+# When the cache is full, less often used symbols will be written to disk.
+# For small to medium size projects (<1000 input files) the default value is
+# probably good enough. For larger projects a too small cache size can cause
+# doxygen to be busy swapping symbols to and from disk most of the time
+# causing a significant performance penalty.
+# If the system has enough physical memory increasing the cache will improve the
+# performance by keeping more symbols in memory. Note that the value works on
+# a logarithmic scale so increasing the size by one will roughly double the
+# memory usage. The cache size is given by this formula:
+# 2^(16+SYMBOL_CACHE_SIZE). The valid range is 0..9, the default is 0,
+# corresponding to a cache size of 2^16 = 65536 symbols.
+
+SYMBOL_CACHE_SIZE = 0
+
+# Similar to the SYMBOL_CACHE_SIZE the size of the symbol lookup cache can be
+# set using LOOKUP_CACHE_SIZE. This cache is used to resolve symbols given
+# their name and scope. Since this can be an expensive process and often the
+# same symbol appear multiple times in the code, doxygen keeps a cache of
+# pre-resolved symbols. If the cache is too small doxygen will become slower.
+# If the cache is too large, memory is wasted. The cache size is given by this
+# formula: 2^(16+LOOKUP_CACHE_SIZE). The valid range is 0..9, the default is 0,
+# corresponding to a cache size of 2^16 = 65536 symbols.
+
+LOOKUP_CACHE_SIZE = 0
+
+#---------------------------------------------------------------------------
+# Build related configuration options
+#---------------------------------------------------------------------------
+
+# If the EXTRACT_ALL tag is set to YES doxygen will assume all entities in
+# documentation are documented, even if no documentation was available.
+# Private class members and static file members will be hidden unless
+# the EXTRACT_PRIVATE and EXTRACT_STATIC tags are set to YES
+
+EXTRACT_ALL = NO
+
+# If the EXTRACT_PRIVATE tag is set to YES all private members of a class
+# will be included in the documentation.
+
+EXTRACT_PRIVATE = NO
+
+# If the EXTRACT_STATIC tag is set to YES all static members of a file
+# will be included in the documentation.
+
+EXTRACT_STATIC = NO
+
+# If the EXTRACT_LOCAL_CLASSES tag is set to YES classes (and structs)
+# defined locally in source files will be included in the documentation.
+# If set to NO only classes defined in header files are included.
+
+EXTRACT_LOCAL_CLASSES = YES
+
+# This flag is only useful for Objective-C code. When set to YES local
+# methods, which are defined in the implementation section but not in
+# the interface are included in the documentation.
+# If set to NO (the default) only methods in the interface are included.
+
+EXTRACT_LOCAL_METHODS = NO
+
+# If this flag is set to YES, the members of anonymous namespaces will be
+# extracted and appear in the documentation as a namespace called
+# 'anonymous_namespace{file}', where file will be replaced with the base +# name of the file that contains the anonymous namespace. By default
+# anonymous namespaces are hidden.
+
+EXTRACT_ANON_NSPACES = NO
+
+# If the HIDE_UNDOC_MEMBERS tag is set to YES, Doxygen will hide all
+# undocumented members of documented classes, files or namespaces.
+# If set to NO (the default) these members will be included in the
+# various overviews, but no documentation section is generated.
+# This option has no effect if EXTRACT_ALL is enabled.
+
+HIDE_UNDOC_MEMBERS = NO
+
+# If the HIDE_UNDOC_CLASSES tag is set to YES, Doxygen will hide all
+# undocumented classes that are normally visible in the class hierarchy.
+# If set to NO (the default) these classes will be included in the various
+# overviews. This option has no effect if EXTRACT_ALL is enabled.
+
+HIDE_UNDOC_CLASSES = NO
+
+# If the HIDE_FRIEND_COMPOUNDS tag is set to YES, Doxygen will hide all
+# friend (class|struct|union) declarations.
+# If set to NO (the default) these declarations will be included in the
+# documentation.
+
+HIDE_FRIEND_COMPOUNDS = NO
+
+# If the HIDE_IN_BODY_DOCS tag is set to YES, Doxygen will hide any
+# documentation blocks found inside the body of a function.
+# If set to NO (the default) these blocks will be appended to the
+# function's detailed documentation block.
+
+HIDE_IN_BODY_DOCS = NO
+
+# The INTERNAL_DOCS tag determines if documentation
+# that is typed after a \internal command is included. If the tag is set
+# to NO (the default) then the documentation will be excluded.
+# Set it to YES to include the internal documentation.
+
+INTERNAL_DOCS = NO
+
+# If the CASE_SENSE_NAMES tag is set to NO then Doxygen will only generate
+# file names in lower-case letters. If set to YES upper-case letters are also
+# allowed. This is useful if you have classes or files whose names only differ
+# in case and if your file system supports case sensitive file names. Windows
+# and Mac users are advised to set this option to NO.
+
+CASE_SENSE_NAMES = NO
+
+# If the HIDE_SCOPE_NAMES tag is set to NO (the default) then Doxygen
+# will show members with their full class and namespace scopes in the
+# documentation. If set to YES the scope will be hidden.
+
+HIDE_SCOPE_NAMES = YES
+
+# If the SHOW_INCLUDE_FILES tag is set to YES (the default) then Doxygen
+# will put a list of the files that are included by a file in the documentation
+# of that file.
+
+SHOW_INCLUDE_FILES = YES
+
+# If the FORCE_LOCAL_INCLUDES tag is set to YES then Doxygen
+# will list include files with double quotes in the documentation
+# rather than with sharp brackets.
+
+FORCE_LOCAL_INCLUDES = NO
+
+# If the INLINE_INFO tag is set to YES (the default) then a tag [inline]
+# is inserted in the documentation for inline members.
+
+INLINE_INFO = YES
+
+# If the SORT_MEMBER_DOCS tag is set to YES (the default) then doxygen
+# will sort the (detailed) documentation of file and class members
+# alphabetically by member name. If set to NO the members will appear in
+# declaration order.
+
+SORT_MEMBER_DOCS = YES
+
+# If the SORT_BRIEF_DOCS tag is set to YES then doxygen will sort the
+# brief documentation of file, namespace and class members alphabetically
+# by member name. If set to NO (the default) the members will appear in
+# declaration order.
+
+SORT_BRIEF_DOCS = NO
+
+# If the SORT_MEMBERS_CTORS_1ST tag is set to YES then doxygen
+# will sort the (brief and detailed) documentation of class members so that
+# constructors and destructors are listed first. If set to NO (the default)
+# the constructors will appear in the respective orders defined by
+# SORT_MEMBER_DOCS and SORT_BRIEF_DOCS.
+# This tag will be ignored for brief docs if SORT_BRIEF_DOCS is set to NO
+# and ignored for detailed docs if SORT_MEMBER_DOCS is set to NO.
+
+SORT_MEMBERS_CTORS_1ST = NO
+
+# If the SORT_GROUP_NAMES tag is set to YES then doxygen will sort the
+# hierarchy of group names into alphabetical order. If set to NO (the default)
+# the group names will appear in their defined order.
+
+SORT_GROUP_NAMES = NO
+
+# If the SORT_BY_SCOPE_NAME tag is set to YES, the class list will be
+# sorted by fully-qualified names, including namespaces. If set to
+# NO (the default), the class list will be sorted only by class name,
+# not including the namespace part.
+# Note: This option is not very useful if HIDE_SCOPE_NAMES is set to YES.
+# Note: This option applies only to the class list, not to the
+# alphabetical list.
+
+SORT_BY_SCOPE_NAME = NO
+
+# If the STRICT_PROTO_MATCHING option is enabled and doxygen fails to
+# do proper type resolution of all parameters of a function it will reject a
+# match between the prototype and the implementation of a member function even
+# if there is only one candidate or it is obvious which candidate to choose
+# by doing a simple string match. By disabling STRICT_PROTO_MATCHING doxygen
+# will still accept a match between prototype and implementation in such cases.
+
+STRICT_PROTO_MATCHING = NO
+
+# The GENERATE_TODOLIST tag can be used to enable (YES) or
+# disable (NO) the todo list. This list is created by putting \todo
+# commands in the documentation.
+
+GENERATE_TODOLIST = YES
+
+# The GENERATE_TESTLIST tag can be used to enable (YES) or
+# disable (NO) the test list. This list is created by putting \test
+# commands in the documentation.
+
+GENERATE_TESTLIST = YES
+
+# The GENERATE_BUGLIST tag can be used to enable (YES) or
+# disable (NO) the bug list. This list is created by putting \bug
+# commands in the documentation.
+
+GENERATE_BUGLIST = YES
+
+# The GENERATE_DEPRECATEDLIST tag can be used to enable (YES) or
+# disable (NO) the deprecated list. This list is created by putting
+# \deprecated commands in the documentation.
+
+GENERATE_DEPRECATEDLIST= YES
+
+# The ENABLED_SECTIONS tag can be used to enable conditional
+# documentation sections, marked by \if sectionname ... \endif.
+
+ENABLED_SECTIONS =
+
+# The MAX_INITIALIZER_LINES tag determines the maximum number of lines
+# the initial value of a variable or macro consists of for it to appear in
+# the documentation. If the initializer consists of more lines than specified
+# here it will be hidden. Use a value of 0 to hide initializers completely.
+# The appearance of the initializer of individual variables and macros in the
+# documentation can be controlled using \showinitializer or \hideinitializer
+# command in the documentation regardless of this setting.
+
+MAX_INITIALIZER_LINES = 30
+
+# Set the SHOW_USED_FILES tag to NO to disable the list of files generated
+# at the bottom of the documentation of classes and structs. If set to YES the
+# list will mention the files that were used to generate the documentation.
+
+SHOW_USED_FILES = YES
+
+# If the sources in your project are distributed over multiple directories
+# then setting the SHOW_DIRECTORIES tag to YES will show the directory hierarchy
+# in the documentation. The default is NO.
+
+SHOW_DIRECTORIES = NO
+
+# Set the SHOW_FILES tag to NO to disable the generation of the Files page.
+# This will remove the Files entry from the Quick Index and from the
+# Folder Tree View (if specified). The default is YES.
+
+SHOW_FILES = YES
+
+# Set the SHOW_NAMESPACES tag to NO to disable the generation of the
+# Namespaces page. This will remove the Namespaces entry from the Quick Index
+# and from the Folder Tree View (if specified). The default is YES.
+
+SHOW_NAMESPACES = YES
+
+# The FILE_VERSION_FILTER tag can be used to specify a program or script that
+# doxygen should invoke to get the current version for each file (typically from
+# the version control system). Doxygen will invoke the program by executing (via
+# popen()) the command <command> <input-file>, where <command> is the value of
+# the FILE_VERSION_FILTER tag, and <input-file> is the name of an input file
+# provided by doxygen. Whatever the program writes to standard output
+# is used as the file version. See the manual for examples.
+
+FILE_VERSION_FILTER =
+
+# The LAYOUT_FILE tag can be used to specify a layout file which will be parsed
+# by doxygen. The layout file controls the global structure of the generated
+# output files in an output format independent way. The create the layout file
+# that represents doxygen's defaults, run doxygen with the -l option.
+# You can optionally specify a file name after the option, if omitted
+# DoxygenLayout.xml will be used as the name of the layout file.
+
+LAYOUT_FILE =
+
+# The CITE_BIB_FILES tag can be used to specify one or more bib files
+# containing the references data. This must be a list of .bib files. The
+# .bib extension is automatically appended if omitted. Using this command
+# requires the bibtex tool to be installed. See also
+# http://en.wikipedia.org/wiki/BibTeX for more info. For LaTeX the style
+# of the bibliography can be controlled using LATEX_BIB_STYLE. To use this
+# feature you need bibtex and perl available in the search path.
+
+CITE_BIB_FILES =
+
+#---------------------------------------------------------------------------
+# configuration options related to warning and progress messages
+#---------------------------------------------------------------------------
+
+# The QUIET tag can be used to turn on/off the messages that are generated
+# by doxygen. Possible values are YES and NO. If left blank NO is used.
+
+QUIET = NO
+
+# The WARNINGS tag can be used to turn on/off the warning messages that are
+# generated by doxygen. Possible values are YES and NO. If left blank
+# NO is used.
+
+WARNINGS = YES
+
+# If WARN_IF_UNDOCUMENTED is set to YES, then doxygen will generate warnings
+# for undocumented members. If EXTRACT_ALL is set to YES then this flag will
+# automatically be disabled.
+
+WARN_IF_UNDOCUMENTED = YES
+
+# If WARN_IF_DOC_ERROR is set to YES, doxygen will generate warnings for
+# potential errors in the documentation, such as not documenting some
+# parameters in a documented function, or documenting parameters that
+# don't exist or using markup commands wrongly.
+
+WARN_IF_DOC_ERROR = YES
+
+# The WARN_NO_PARAMDOC option can be enabled to get warnings for
+# functions that are documented, but have no documentation for their parameters
+# or return value. If set to NO (the default) doxygen will only warn about
+# wrong or incomplete parameter documentation, but not about the absence of
+# documentation.
+
+WARN_NO_PARAMDOC = YES
+
+# The WARN_FORMAT tag determines the format of the warning messages that
+# doxygen can produce. The string should contain the $file, $line, and $text
+# tags, which will be replaced by the file and line number from which the
+# warning originated and the warning text. Optionally the format may contain
+# $version, which will be replaced by the version of the file (if it could
+# be obtained via FILE_VERSION_FILTER)
+
+WARN_FORMAT = "$file:$line: $text"
+
+# The WARN_LOGFILE tag can be used to specify a file to which warning
+# and error messages should be written. If left blank the output is written
+# to stderr.
+
+WARN_LOGFILE =
+
+#---------------------------------------------------------------------------
+# configuration options related to the input files
+#---------------------------------------------------------------------------
+
+# The INPUT tag can be used to specify the files and/or directories that contain
+# documented source files. You may enter file names like "myfile.cpp" or
+# directories like "/usr/src/myproject". Separate the files or directories
+# with spaces.
+
+INPUT = src
+
+# This tag can be used to specify the character encoding of the source files
+# that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is
+# also the default input encoding. Doxygen uses libiconv (or the iconv built
+# into libc) for the transcoding. See http://www.gnu.org/software/libiconv for
+# the list of possible encodings.
+
+INPUT_ENCODING = UTF-8
+
+# If the value of the INPUT tag contains directories, you can use the
+# FILE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp
+# and *.h) to filter out the source-files in the directories. If left
+# blank the following patterns are tested:
+# *.c *.cc *.cxx *.cpp *.c++ *.d *.java *.ii *.ixx *.ipp *.i++ *.inl *.h *.hh
+# *.hxx *.hpp *.h++ *.idl *.odl *.cs *.php *.php3 *.inc *.m *.mm *.dox *.py
+# *.f90 *.f *.for *.vhd *.vhdl
+
+FILE_PATTERNS = sox.h
+
+# The RECURSIVE tag can be used to turn specify whether or not subdirectories
+# should be searched for input files as well. Possible values are YES and NO.
+# If left blank NO is used.
+
+RECURSIVE = NO
+
+# The EXCLUDE tag can be used to specify files and/or directories that should be
+# excluded from the INPUT source files. This way you can easily exclude a
+# subdirectory from a directory tree whose root is specified with the INPUT tag.
+# Note that relative paths are relative to the directory from which doxygen is
+# run.
+
+EXCLUDE =
+
+# The EXCLUDE_SYMLINKS tag can be used to select whether or not files or
+# directories that are symbolic links (a Unix file system feature) are excluded
+# from the input.
+
+EXCLUDE_SYMLINKS = NO
+
+# If the value of the INPUT tag contains directories, you can use the
+# EXCLUDE_PATTERNS tag to specify one or more wildcard patterns to exclude
+# certain files from those directories. Note that the wildcards are matched
+# against the file with absolute path, so to exclude all test directories
+# for example use the pattern */test/*
+
+EXCLUDE_PATTERNS =
+
+# The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names
+# (namespaces, classes, functions, etc.) that should be excluded from the
+# output. The symbol name can be a fully qualified name, a word, or if the
+# wildcard * is used, a substring. Examples: ANamespace, AClass,
+# AClass::ANamespace, ANamespace::*Test
+
+EXCLUDE_SYMBOLS =
+
+# The EXAMPLE_PATH tag can be used to specify one or more files or
+# directories that contain example code fragments that are included (see
+# the \include command).
+
+EXAMPLE_PATH =
+
+# If the value of the EXAMPLE_PATH tag contains directories, you can use the
+# EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp
+# and *.h) to filter out the source-files in the directories. If left
+# blank all files are included.
+
+EXAMPLE_PATTERNS = *
+
+# If the EXAMPLE_RECURSIVE tag is set to YES then subdirectories will be
+# searched for input files to be used with the \include or \dontinclude
+# commands irrespective of the value of the RECURSIVE tag.
+# Possible values are YES and NO. If left blank NO is used.
+
+EXAMPLE_RECURSIVE = NO
+
+# The IMAGE_PATH tag can be used to specify one or more files or
+# directories that contain image that are included in the documentation (see
+# the \image command).
+
+IMAGE_PATH =
+
+# The INPUT_FILTER tag can be used to specify a program that doxygen should
+# invoke to filter for each input file. Doxygen will invoke the filter program
+# by executing (via popen()) the command <filter> <input-file>, where <filter>
+# is the value of the INPUT_FILTER tag, and <input-file> is the name of an
+# input file. Doxygen will then use the output that the filter program writes
+# to standard output. If FILTER_PATTERNS is specified, this tag will be
+# ignored.
+
+INPUT_FILTER =
+
+# The FILTER_PATTERNS tag can be used to specify filters on a per file pattern
+# basis. Doxygen will compare the file name with each pattern and apply the
+# filter if there is a match. The filters are a list of the form:
+# pattern=filter (like *.cpp=my_cpp_filter). See INPUT_FILTER for further
+# info on how filters are used. If FILTER_PATTERNS is empty or if
+# non of the patterns match the file name, INPUT_FILTER is applied.
+
+FILTER_PATTERNS =
+
+# If the FILTER_SOURCE_FILES tag is set to YES, the input filter (if set using
+# INPUT_FILTER) will be used to filter the input files when producing source
+# files to browse (i.e. when SOURCE_BROWSER is set to YES).
+
+FILTER_SOURCE_FILES = NO
+
+# The FILTER_SOURCE_PATTERNS tag can be used to specify source filters per file
+# pattern. A pattern will override the setting for FILTER_PATTERN (if any)
+# and it is also possible to disable source filtering for a specific pattern
+# using *.ext= (so without naming a filter). This option only has effect when
+# FILTER_SOURCE_FILES is enabled.
+
+FILTER_SOURCE_PATTERNS =
+
+#---------------------------------------------------------------------------
+# configuration options related to source browsing
+#---------------------------------------------------------------------------
+
+# If the SOURCE_BROWSER tag is set to YES then a list of source files will
+# be generated. Documented entities will be cross-referenced with these sources.
+# Note: To get rid of all source code in the generated output, make sure also
+# VERBATIM_HEADERS is set to NO.
+
+SOURCE_BROWSER = NO
+
+# Setting the INLINE_SOURCES tag to YES will include the body
+# of functions and classes directly in the documentation.
+
+INLINE_SOURCES = NO
+
+# Setting the STRIP_CODE_COMMENTS tag to YES (the default) will instruct
+# doxygen to hide any special comment blocks from generated source code
+# fragments. Normal C and C++ comments will always remain visible.
+
+STRIP_CODE_COMMENTS = YES
+
+# If the REFERENCED_BY_RELATION tag is set to YES
+# then for each documented function all documented
+# functions referencing it will be listed.
+
+REFERENCED_BY_RELATION = NO
+
+# If the REFERENCES_RELATION tag is set to YES
+# then for each documented function all documented entities
+# called/used by that function will be listed.
+
+REFERENCES_RELATION = NO
+
+# If the REFERENCES_LINK_SOURCE tag is set to YES (the default)
+# and SOURCE_BROWSER tag is set to YES, then the hyperlinks from
+# functions in REFERENCES_RELATION and REFERENCED_BY_RELATION lists will
+# link to the source code. Otherwise they will link to the documentation.
+
+REFERENCES_LINK_SOURCE = YES
+
+# If the USE_HTAGS tag is set to YES then the references to source code
+# will point to the HTML generated by the htags(1) tool instead of doxygen
+# built-in source browser. The htags tool is part of GNU's global source
+# tagging system (see http://www.gnu.org/software/global/global.html). You
+# will need version 4.8.6 or higher.
+
+USE_HTAGS = NO
+
+# If the VERBATIM_HEADERS tag is set to YES (the default) then Doxygen
+# will generate a verbatim copy of the header file for each class for
+# which an include is specified. Set to NO to disable this.
+
+VERBATIM_HEADERS = YES
+
+#---------------------------------------------------------------------------
+# configuration options related to the alphabetical class index
+#---------------------------------------------------------------------------
+
+# If the ALPHABETICAL_INDEX tag is set to YES, an alphabetical index
+# of all compounds will be generated. Enable this if the project
+# contains a lot of classes, structs, unions or interfaces.
+
+ALPHABETICAL_INDEX = YES
+
+# If the alphabetical index is enabled (see ALPHABETICAL_INDEX) then
+# the COLS_IN_ALPHA_INDEX tag can be used to specify the number of columns
+# in which this list will be split (can be a number in the range [1..20])
+
+COLS_IN_ALPHA_INDEX = 5
+
+# In case all classes in a project start with a common prefix, all
+# classes will be put under the same header in the alphabetical index.
+# The IGNORE_PREFIX tag can be used to specify one or more prefixes that
+# should be ignored while generating the index headers.
+
+IGNORE_PREFIX =
+
+#---------------------------------------------------------------------------
+# configuration options related to the HTML output
+#---------------------------------------------------------------------------
+
+# If the GENERATE_HTML tag is set to YES (the default) Doxygen will
+# generate HTML output.
+
+GENERATE_HTML = YES
+
+# The HTML_OUTPUT tag is used to specify where the HTML docs will be put.
+# If a relative path is entered the value of OUTPUT_DIRECTORY will be
+# put in front of it. If left blank `html' will be used as the default path.
+
+HTML_OUTPUT = html
+
+# The HTML_FILE_EXTENSION tag can be used to specify the file extension for
+# each generated HTML page (for example: .htm,.php,.asp). If it is left blank
+# doxygen will generate files with .html extension.
+
+HTML_FILE_EXTENSION = .html
+
+# The HTML_HEADER tag can be used to specify a personal HTML header for
+# each generated HTML page. If it is left blank doxygen will generate a
+# standard header. Note that when using a custom header you are responsible
+# for the proper inclusion of any scripts and style sheets that doxygen
+# needs, which is dependent on the configuration options used.
+# It is advised to generate a default header using "doxygen -w html
+# header.html footer.html stylesheet.css YourConfigFile" and then modify
+# that header. Note that the header is subject to change so you typically
+# have to redo this when upgrading to a newer version of doxygen or when
+# changing the value of configuration settings such as GENERATE_TREEVIEW!
+
+HTML_HEADER =
+
+# The HTML_FOOTER tag can be used to specify a personal HTML footer for
+# each generated HTML page. If it is left blank doxygen will generate a
+# standard footer.
+
+HTML_FOOTER =
+
+# The HTML_STYLESHEET tag can be used to specify a user-defined cascading
+# style sheet that is used by each HTML page. It can be used to
+# fine-tune the look of the HTML output. If the tag is left blank doxygen
+# will generate a default style sheet. Note that doxygen will try to copy
+# the style sheet file to the HTML output directory, so don't put your own
+# style sheet in the HTML output directory as well, or it will be erased!
+
+HTML_STYLESHEET =
+
+# The HTML_EXTRA_FILES tag can be used to specify one or more extra images or
+# other source files which should be copied to the HTML output directory. Note
+# that these files will be copied to the base HTML output directory. Use the
+# $relpath$ marker in the HTML_HEADER and/or HTML_FOOTER files to load these
+# files. In the HTML_STYLESHEET file, use the file name only. Also note that
+# the files will be copied as-is; there are no commands or markers available.
+
+HTML_EXTRA_FILES =
+
+# The HTML_COLORSTYLE_HUE tag controls the color of the HTML output.
+# Doxygen will adjust the colors in the style sheet and background images
+# according to this color. Hue is specified as an angle on a colorwheel,
+# see http://en.wikipedia.org/wiki/Hue for more information.
+# For instance the value 0 represents red, 60 is yellow, 120 is green,
+# 180 is cyan, 240 is blue, 300 purple, and 360 is red again.
+# The allowed range is 0 to 359.
+
+HTML_COLORSTYLE_HUE = 220
+
+# The HTML_COLORSTYLE_SAT tag controls the purity (or saturation) of
+# the colors in the HTML output. For a value of 0 the output will use
+# grayscales only. A value of 255 will produce the most vivid colors.
+
+HTML_COLORSTYLE_SAT = 100
+
+# The HTML_COLORSTYLE_GAMMA tag controls the gamma correction applied to
+# the luminance component of the colors in the HTML output. Values below
+# 100 gradually make the output lighter, whereas values above 100 make
+# the output darker. The value divided by 100 is the actual gamma applied,
+# so 80 represents a gamma of 0.8, The value 220 represents a gamma of 2.2,
+# and 100 does not change the gamma.
+
+HTML_COLORSTYLE_GAMMA = 80
+
+# If the HTML_TIMESTAMP tag is set to YES then the footer of each generated HTML
+# page will contain the date and time when the page was generated. Setting
+# this to NO can help when comparing the output of multiple runs.
+
+HTML_TIMESTAMP = YES
+
+# If the HTML_ALIGN_MEMBERS tag is set to YES, the members of classes,
+# files or namespaces will be aligned in HTML using tables. If set to
+# NO a bullet list will be used.
+
+HTML_ALIGN_MEMBERS = YES
+
+# If the HTML_DYNAMIC_SECTIONS tag is set to YES then the generated HTML
+# documentation will contain sections that can be hidden and shown after the
+# page has loaded. For this to work a browser that supports
+# JavaScript and DHTML is required (for instance Mozilla 1.0+, Firefox
+# Netscape 6.0+, Internet explorer 5.0+, Konqueror, or Safari).
+
+HTML_DYNAMIC_SECTIONS = NO
+
+# If the GENERATE_DOCSET tag is set to YES, additional index files
+# will be generated that can be used as input for Apple's Xcode 3
+# integrated development environment, introduced with OSX 10.5 (Leopard).
+# To create a documentation set, doxygen will generate a Makefile in the
+# HTML output directory. Running make will produce the docset in that
+# directory and running "make install" will install the docset in
+# ~/Library/Developer/Shared/Documentation/DocSets so that Xcode will find
+# it at startup.
+# See http://developer.apple.com/tools/creatingdocsetswithdoxygen.html
+# for more information.
+
+GENERATE_DOCSET = NO
+
+# When GENERATE_DOCSET tag is set to YES, this tag determines the name of the
+# feed. A documentation feed provides an umbrella under which multiple
+# documentation sets from a single provider (such as a company or product suite)
+# can be grouped.
+
+DOCSET_FEEDNAME = "Doxygen generated docs"
+
+# When GENERATE_DOCSET tag is set to YES, this tag specifies a string that
+# should uniquely identify the documentation set bundle. This should be a
+# reverse domain-name style string, e.g. com.mycompany.MyDocSet. Doxygen
+# will append .docset to the name.
+
+DOCSET_BUNDLE_ID = org.doxygen.Project
+
+# When GENERATE_PUBLISHER_ID tag specifies a string that should uniquely identify
+# the documentation publisher. This should be a reverse domain-name style
+# string, e.g. com.mycompany.MyDocSet.documentation.
+
+DOCSET_PUBLISHER_ID = org.doxygen.Publisher
+
+# The GENERATE_PUBLISHER_NAME tag identifies the documentation publisher.
+
+DOCSET_PUBLISHER_NAME = Publisher
+
+# If the GENERATE_HTMLHELP tag is set to YES, additional index files
+# will be generated that can be used as input for tools like the
+# Microsoft HTML help workshop to generate a compiled HTML help file (.chm)
+# of the generated HTML documentation.
+
+GENERATE_HTMLHELP = NO
+
+# If the GENERATE_HTMLHELP tag is set to YES, the CHM_FILE tag can
+# be used to specify the file name of the resulting .chm file. You
+# can add a path in front of the file if the result should not be
+# written to the html output directory.
+
+CHM_FILE =
+
+# If the GENERATE_HTMLHELP tag is set to YES, the HHC_LOCATION tag can
+# be used to specify the location (absolute path including file name) of
+# the HTML help compiler (hhc.exe). If non-empty doxygen will try to run
+# the HTML help compiler on the generated index.hhp.
+
+HHC_LOCATION =
+
+# If the GENERATE_HTMLHELP tag is set to YES, the GENERATE_CHI flag
+# controls if a separate .chi index file is generated (YES) or that
+# it should be included in the master .chm file (NO).
+
+GENERATE_CHI = NO
+
+# If the GENERATE_HTMLHELP tag is set to YES, the CHM_INDEX_ENCODING
+# is used to encode HtmlHelp index (hhk), content (hhc) and project file
+# content.
+
+CHM_INDEX_ENCODING =
+
+# If the GENERATE_HTMLHELP tag is set to YES, the BINARY_TOC flag
+# controls whether a binary table of contents is generated (YES) or a
+# normal table of contents (NO) in the .chm file.
+
+BINARY_TOC = NO
+
+# The TOC_EXPAND flag can be set to YES to add extra items for group members
+# to the contents of the HTML help documentation and to the tree view.
+
+TOC_EXPAND = NO
+
+# If the GENERATE_QHP tag is set to YES and both QHP_NAMESPACE and
+# QHP_VIRTUAL_FOLDER are set, an additional index file will be generated
+# that can be used as input for Qt's qhelpgenerator to generate a
+# Qt Compressed Help (.qch) of the generated HTML documentation.
+
+GENERATE_QHP = NO
+
+# If the QHG_LOCATION tag is specified, the QCH_FILE tag can
+# be used to specify the file name of the resulting .qch file.
+# The path specified is relative to the HTML output folder.
+
+QCH_FILE =
+
+# The QHP_NAMESPACE tag specifies the namespace to use when generating
+# Qt Help Project output. For more information please see
+# http://doc.trolltech.com/qthelpproject.html#namespace
+
+QHP_NAMESPACE = org.doxygen.Project
+
+# The QHP_VIRTUAL_FOLDER tag specifies the namespace to use when generating
+# Qt Help Project output. For more information please see
+# http://doc.trolltech.com/qthelpproject.html#virtual-folders
+
+QHP_VIRTUAL_FOLDER = doc
+
+# If QHP_CUST_FILTER_NAME is set, it specifies the name of a custom filter to
+# add. For more information please see
+# http://doc.trolltech.com/qthelpproject.html#custom-filters
+
+QHP_CUST_FILTER_NAME =
+
+# The QHP_CUST_FILT_ATTRS tag specifies the list of the attributes of the
+# custom filter to add. For more information please see
+# <a href="http://doc.trolltech.com/qthelpproject.html#custom-filters">
+# Qt Help Project / Custom Filters</a>.
+
+QHP_CUST_FILTER_ATTRS =
+
+# The QHP_SECT_FILTER_ATTRS tag specifies the list of the attributes this
+# project's
+# filter section matches.
+# <a href="http://doc.trolltech.com/qthelpproject.html#filter-attributes">
+# Qt Help Project / Filter Attributes</a>.
+
+QHP_SECT_FILTER_ATTRS =
+
+# If the GENERATE_QHP tag is set to YES, the QHG_LOCATION tag can
+# be used to specify the location of Qt's qhelpgenerator.
+# If non-empty doxygen will try to run qhelpgenerator on the generated
+# .qhp file.
+
+QHG_LOCATION =
+
+# If the GENERATE_ECLIPSEHELP tag is set to YES, additional index files
+# will be generated, which together with the HTML files, form an Eclipse help
+# plugin. To install this plugin and make it available under the help contents
+# menu in Eclipse, the contents of the directory containing the HTML and XML
+# files needs to be copied into the plugins directory of eclipse. The name of
+# the directory within the plugins directory should be the same as
+# the ECLIPSE_DOC_ID value. After copying Eclipse needs to be restarted before
+# the help appears.
+
+GENERATE_ECLIPSEHELP = NO
+
+# A unique identifier for the eclipse help plugin. When installing the plugin
+# the directory name containing the HTML and XML files should also have
+# this name.
+
+ECLIPSE_DOC_ID = org.doxygen.Project
+
+# The DISABLE_INDEX tag can be used to turn on/off the condensed index (tabs)
+# at top of each HTML page. The value NO (the default) enables the index and
+# the value YES disables it. Since the tabs have the same information as the
+# navigation tree you can set this option to NO if you already set
+# GENERATE_TREEVIEW to YES.
+
+DISABLE_INDEX = NO
+
+# The GENERATE_TREEVIEW tag is used to specify whether a tree-like index
+# structure should be generated to display hierarchical information.
+# If the tag value is set to YES, a side panel will be generated
+# containing a tree-like index structure (just like the one that
+# is generated for HTML Help). For this to work a browser that supports
+# JavaScript, DHTML, CSS and frames is required (i.e. any modern browser).
+# Windows users are probably better off using the HTML help feature.
+# Since the tree basically has the same information as the tab index you
+# could consider to set DISABLE_INDEX to NO when enabling this option.
+
+GENERATE_TREEVIEW = NO
+
+# The ENUM_VALUES_PER_LINE tag can be used to set the number of enum values
+# (range [0,1..20]) that doxygen will group on one line in the generated HTML
+# documentation. Note that a value of 0 will completely suppress the enum
+# values from appearing in the overview section.
+
+ENUM_VALUES_PER_LINE = 4
+
+# By enabling USE_INLINE_TREES, doxygen will generate the Groups, Directories,
+# and Class Hierarchy pages using a tree view instead of an ordered list.
+
+USE_INLINE_TREES = NO
+
+# If the treeview is enabled (see GENERATE_TREEVIEW) then this tag can be
+# used to set the initial width (in pixels) of the frame in which the tree
+# is shown.
+
+TREEVIEW_WIDTH = 250
+
+# When the EXT_LINKS_IN_WINDOW option is set to YES doxygen will open
+# links to external symbols imported via tag files in a separate window.
+
+EXT_LINKS_IN_WINDOW = NO
+
+# Use this tag to change the font size of Latex formulas included
+# as images in the HTML documentation. The default is 10. Note that
+# when you change the font size after a successful doxygen run you need
+# to manually remove any form_*.png images from the HTML output directory
+# to force them to be regenerated.
+
+FORMULA_FONTSIZE = 10
+
+# Use the FORMULA_TRANPARENT tag to determine whether or not the images
+# generated for formulas are transparent PNGs. Transparent PNGs are
+# not supported properly for IE 6.0, but are supported on all modern browsers.
+# Note that when changing this option you need to delete any form_*.png files
+# in the HTML output before the changes have effect.
+
+FORMULA_TRANSPARENT = YES
+
+# Enable the USE_MATHJAX option to render LaTeX formulas using MathJax
+# (see http://www.mathjax.org) which uses client side Javascript for the
+# rendering instead of using prerendered bitmaps. Use this if you do not
+# have LaTeX installed or if you want to formulas look prettier in the HTML
+# output. When enabled you also need to install MathJax separately and
+# configure the path to it using the MATHJAX_RELPATH option.
+
+USE_MATHJAX = NO
+
+# When MathJax is enabled you need to specify the location relative to the
+# HTML output directory using the MATHJAX_RELPATH option. The destination
+# directory should contain the MathJax.js script. For instance, if the mathjax
+# directory is located at the same level as the HTML output directory, then
+# MATHJAX_RELPATH should be ../mathjax. The default value points to the
+# mathjax.org site, so you can quickly see the result without installing
+# MathJax, but it is strongly recommended to install a local copy of MathJax
+# before deployment.
+
+MATHJAX_RELPATH = http://www.mathjax.org/mathjax
+
+# The MATHJAX_EXTENSIONS tag can be used to specify one or MathJax extension
+# names that should be enabled during MathJax rendering.
+
+MATHJAX_EXTENSIONS =
+
+# When the SEARCHENGINE tag is enabled doxygen will generate a search box
+# for the HTML output. The underlying search engine uses javascript
+# and DHTML and should work on any modern browser. Note that when using
+# HTML help (GENERATE_HTMLHELP), Qt help (GENERATE_QHP), or docsets
+# (GENERATE_DOCSET) there is already a search function so this one should
+# typically be disabled. For large projects the javascript based search engine
+# can be slow, then enabling SERVER_BASED_SEARCH may provide a better solution.
+
+SEARCHENGINE = YES
+
+# When the SERVER_BASED_SEARCH tag is enabled the search engine will be
+# implemented using a PHP enabled web server instead of at the web client
+# using Javascript. Doxygen will generate the search PHP script and index
+# file to put on the web server. The advantage of the server
+# based approach is that it scales better to large projects and allows
+# full text search. The disadvantages are that it is more difficult to setup
+# and does not have live searching capabilities.
+
+SERVER_BASED_SEARCH = NO
+
+#---------------------------------------------------------------------------
+# configuration options related to the LaTeX output
+#---------------------------------------------------------------------------
+
+# If the GENERATE_LATEX tag is set to YES (the default) Doxygen will
+# generate Latex output.
+
+GENERATE_LATEX = NO
+
+# The LATEX_OUTPUT tag is used to specify where the LaTeX docs will be put.
+# If a relative path is entered the value of OUTPUT_DIRECTORY will be
+# put in front of it. If left blank `latex' will be used as the default path.
+
+LATEX_OUTPUT = latex
+
+# The LATEX_CMD_NAME tag can be used to specify the LaTeX command name to be
+# invoked. If left blank `latex' will be used as the default command name.
+# Note that when enabling USE_PDFLATEX this option is only used for
+# generating bitmaps for formulas in the HTML output, but not in the
+# Makefile that is written to the output directory.
+
+LATEX_CMD_NAME = latex
+
+# The MAKEINDEX_CMD_NAME tag can be used to specify the command name to
+# generate index for LaTeX. If left blank `makeindex' will be used as the
+# default command name.
+
+MAKEINDEX_CMD_NAME = makeindex
+
+# If the COMPACT_LATEX tag is set to YES Doxygen generates more compact
+# LaTeX documents. This may be useful for small projects and may help to
+# save some trees in general.
+
+COMPACT_LATEX = NO
+
+# The PAPER_TYPE tag can be used to set the paper type that is used
+# by the printer. Possible values are: a4, letter, legal and
+# executive. If left blank a4wide will be used.
+
+PAPER_TYPE = a4
+
+# The EXTRA_PACKAGES tag can be to specify one or more names of LaTeX
+# packages that should be included in the LaTeX output.
+
+EXTRA_PACKAGES =
+
+# The LATEX_HEADER tag can be used to specify a personal LaTeX header for
+# the generated latex document. The header should contain everything until
+# the first chapter. If it is left blank doxygen will generate a
+# standard header. Notice: only use this tag if you know what you are doing!
+
+LATEX_HEADER =
+
+# The LATEX_FOOTER tag can be used to specify a personal LaTeX footer for
+# the generated latex document. The footer should contain everything after
+# the last chapter. If it is left blank doxygen will generate a
+# standard footer. Notice: only use this tag if you know what you are doing!
+
+LATEX_FOOTER =
+
+# If the PDF_HYPERLINKS tag is set to YES, the LaTeX that is generated
+# is prepared for conversion to pdf (using ps2pdf). The pdf file will
+# contain links (just like the HTML output) instead of page references
+# This makes the output suitable for online browsing using a pdf viewer.
+
+PDF_HYPERLINKS = YES
+
+# If the USE_PDFLATEX tag is set to YES, pdflatex will be used instead of
+# plain latex in the generated Makefile. Set this option to YES to get a
+# higher quality PDF documentation.
+
+USE_PDFLATEX = YES
+
+# If the LATEX_BATCHMODE tag is set to YES, doxygen will add the \\batchmode.
+# command to the generated LaTeX files. This will instruct LaTeX to keep
+# running if errors occur, instead of asking the user for help.
+# This option is also used when generating formulas in HTML.
+
+LATEX_BATCHMODE = NO
+
+# If LATEX_HIDE_INDICES is set to YES then doxygen will not
+# include the index chapters (such as File Index, Compound Index, etc.)
+# in the output.
+
+LATEX_HIDE_INDICES = NO
+
+# If LATEX_SOURCE_CODE is set to YES then doxygen will include
+# source code with syntax highlighting in the LaTeX output.
+# Note that which sources are shown also depends on other settings
+# such as SOURCE_BROWSER.
+
+LATEX_SOURCE_CODE = NO
+
+# The LATEX_BIB_STYLE tag can be used to specify the style to use for the
+# bibliography, e.g. plainnat, or ieeetr. The default style is "plain". See
+# http://en.wikipedia.org/wiki/BibTeX for more info.
+
+LATEX_BIB_STYLE = plain
+
+#---------------------------------------------------------------------------
+# configuration options related to the RTF output
+#---------------------------------------------------------------------------
+
+# If the GENERATE_RTF tag is set to YES Doxygen will generate RTF output
+# The RTF output is optimized for Word 97 and may not look very pretty with
+# other RTF readers or editors.
+
+GENERATE_RTF = NO
+
+# The RTF_OUTPUT tag is used to specify where the RTF docs will be put.
+# If a relative path is entered the value of OUTPUT_DIRECTORY will be
+# put in front of it. If left blank `rtf' will be used as the default path.
+
+RTF_OUTPUT = rtf
+
+# If the COMPACT_RTF tag is set to YES Doxygen generates more compact
+# RTF documents. This may be useful for small projects and may help to
+# save some trees in general.
+
+COMPACT_RTF = NO
+
+# If the RTF_HYPERLINKS tag is set to YES, the RTF that is generated
+# will contain hyperlink fields. The RTF file will
+# contain links (just like the HTML output) instead of page references.
+# This makes the output suitable for online browsing using WORD or other
+# programs which support those fields.
+# Note: wordpad (write) and others do not support links.
+
+RTF_HYPERLINKS = NO
+
+# Load style sheet definitions from file. Syntax is similar to doxygen's
+# config file, i.e. a series of assignments. You only have to provide
+# replacements, missing definitions are set to their default value.
+
+RTF_STYLESHEET_FILE =
+
+# Set optional variables used in the generation of an rtf document.
+# Syntax is similar to doxygen's config file.
+
+RTF_EXTENSIONS_FILE =
+
+#---------------------------------------------------------------------------
+# configuration options related to the man page output
+#---------------------------------------------------------------------------
+
+# If the GENERATE_MAN tag is set to YES (the default) Doxygen will
+# generate man pages
+
+GENERATE_MAN = NO
+
+# The MAN_OUTPUT tag is used to specify where the man pages will be put.
+# If a relative path is entered the value of OUTPUT_DIRECTORY will be
+# put in front of it. If left blank `man' will be used as the default path.
+
+MAN_OUTPUT = man
+
+# The MAN_EXTENSION tag determines the extension that is added to
+# the generated man pages (default is the subroutine's section .3)
+
+MAN_EXTENSION = .3
+
+# If the MAN_LINKS tag is set to YES and Doxygen generates man output,
+# then it will generate one additional man file for each entity
+# documented in the real man page(s). These additional files
+# only source the real man page, but without them the man command
+# would be unable to find the correct page. The default is NO.
+
+MAN_LINKS = NO
+
+#---------------------------------------------------------------------------
+# configuration options related to the XML output
+#---------------------------------------------------------------------------
+
+# If the GENERATE_XML tag is set to YES Doxygen will
+# generate an XML file that captures the structure of
+# the code including all documentation.
+
+GENERATE_XML = NO
+
+# The XML_OUTPUT tag is used to specify where the XML pages will be put.
+# If a relative path is entered the value of OUTPUT_DIRECTORY will be
+# put in front of it. If left blank `xml' will be used as the default path.
+
+XML_OUTPUT = xml
+
+# The XML_SCHEMA tag can be used to specify an XML schema,
+# which can be used by a validating XML parser to check the
+# syntax of the XML files.
+
+XML_SCHEMA =
+
+# The XML_DTD tag can be used to specify an XML DTD,
+# which can be used by a validating XML parser to check the
+# syntax of the XML files.
+
+XML_DTD =
+
+# If the XML_PROGRAMLISTING tag is set to YES Doxygen will
+# dump the program listings (including syntax highlighting
+# and cross-referencing information) to the XML output. Note that
+# enabling this will significantly increase the size of the XML output.
+
+XML_PROGRAMLISTING = YES
+
+#---------------------------------------------------------------------------
+# configuration options for the AutoGen Definitions output
+#---------------------------------------------------------------------------
+
+# If the GENERATE_AUTOGEN_DEF tag is set to YES Doxygen will
+# generate an AutoGen Definitions (see autogen.sf.net) file
+# that captures the structure of the code including all
+# documentation. Note that this feature is still experimental
+# and incomplete at the moment.
+
+GENERATE_AUTOGEN_DEF = NO
+
+#---------------------------------------------------------------------------
+# configuration options related to the Perl module output
+#---------------------------------------------------------------------------
+
+# If the GENERATE_PERLMOD tag is set to YES Doxygen will
+# generate a Perl module file that captures the structure of
+# the code including all documentation. Note that this
+# feature is still experimental and incomplete at the
+# moment.
+
+GENERATE_PERLMOD = NO
+
+# If the PERLMOD_LATEX tag is set to YES Doxygen will generate
+# the necessary Makefile rules, Perl scripts and LaTeX code to be able
+# to generate PDF and DVI output from the Perl module output.
+
+PERLMOD_LATEX = NO
+
+# If the PERLMOD_PRETTY tag is set to YES the Perl module output will be
+# nicely formatted so it can be parsed by a human reader. This is useful
+# if you want to understand what is going on. On the other hand, if this
+# tag is set to NO the size of the Perl module output will be much smaller
+# and Perl will parse it just the same.
+
+PERLMOD_PRETTY = YES
+
+# The names of the make variables in the generated doxyrules.make file
+# are prefixed with the string contained in PERLMOD_MAKEVAR_PREFIX.
+# This is useful so different doxyrules.make files included by the same
+# Makefile don't overwrite each other's variables.
+
+PERLMOD_MAKEVAR_PREFIX =
+
+#---------------------------------------------------------------------------
+# Configuration options related to the preprocessor
+#---------------------------------------------------------------------------
+
+# If the ENABLE_PREPROCESSING tag is set to YES (the default) Doxygen will
+# evaluate all C-preprocessor directives found in the sources and include
+# files.
+
+ENABLE_PREPROCESSING = YES
+
+# If the MACRO_EXPANSION tag is set to YES Doxygen will expand all macro
+# names in the source code. If set to NO (the default) only conditional
+# compilation will be performed. Macro expansion can be done in a controlled
+# way by setting EXPAND_ONLY_PREDEF to YES.
+
+MACRO_EXPANSION = NO
+
+# If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES
+# then the macro expansion is limited to the macros specified with the
+# PREDEFINED and EXPAND_AS_DEFINED tags.
+
+EXPAND_ONLY_PREDEF = YES
+
+# If the SEARCH_INCLUDES tag is set to YES (the default) the includes files
+# pointed to by INCLUDE_PATH will be searched when a #include is found.
+
+SEARCH_INCLUDES = YES
+
+# The INCLUDE_PATH tag can be used to specify one or more directories that
+# contain include files that are not input files but should be processed by
+# the preprocessor.
+
+INCLUDE_PATH =
+
+# You can use the INCLUDE_FILE_PATTERNS tag to specify one or more wildcard
+# patterns (like *.h and *.hpp) to filter out the header-files in the
+# directories. If left blank, the patterns specified with FILE_PATTERNS will
+# be used.
+
+INCLUDE_FILE_PATTERNS =
+
+# The PREDEFINED tag can be used to specify one or more macro names that
+# are defined before the preprocessor is started (similar to the -D option of
+# gcc). The argument of the tag is a list of macros of the form: name
+# or name=definition (no spaces). If the definition and the = are
+# omitted =1 is assumed. To prevent a macro definition from being
+# undefined via #undef or recursively expanded use the := operator
+# instead of the = operator.
+
+PREDEFINED = SCHAR_MIN=(-128) \
+ SCHAR_MAX=127 \
+ UCHAR_MAX=0xff \
+ SHRT_MAX=32767 \
+ SHRT_MIN=(-32768) \
+ USHRT_MAX=0xffff \
+ INT_MAX=2147483647 \
+ INT_MIN=(-2147483647-1) \
+ UINT_MAX=0xffffffff
+
+# If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then
+# this tag can be used to specify a list of macro names that should be expanded.
+# The macro definition that is found in the sources will be used.
+# Use the PREDEFINED tag if you want to use a different macro definition that
+# overrules the definition found in the source code.
+
+EXPAND_AS_DEFINED =
+
+# If the SKIP_FUNCTION_MACROS tag is set to YES (the default) then
+# doxygen's preprocessor will remove all references to function-like macros
+# that are alone on a line, have an all uppercase name, and do not end with a
+# semicolon, because these will confuse the parser if not removed.
+
+SKIP_FUNCTION_MACROS = YES
+
+#---------------------------------------------------------------------------
+# Configuration::additions related to external references
+#---------------------------------------------------------------------------
+
+# The TAGFILES option can be used to specify one or more tagfiles.
+# Optionally an initial location of the external documentation
+# can be added for each tagfile. The format of a tag file without
+# this location is as follows:
+# TAGFILES = file1 file2 ...
+# Adding location for the tag files is done as follows:
+# TAGFILES = file1=loc1 "file2 = loc2" ...
+# where "loc1" and "loc2" can be relative or absolute paths or
+# URLs. If a location is present for each tag, the installdox tool
+# does not have to be run to correct the links.
+# Note that each tag file must have a unique name
+# (where the name does NOT include the path)
+# If a tag file is not located in the directory in which doxygen
+# is run, you must also specify the path to the tagfile here.
+
+TAGFILES =
+
+# When a file name is specified after GENERATE_TAGFILE, doxygen will create
+# a tag file that is based on the input files it reads.
+
+GENERATE_TAGFILE =
+
+# If the ALLEXTERNALS tag is set to YES all external classes will be listed
+# in the class index. If set to NO only the inherited external classes
+# will be listed.
+
+ALLEXTERNALS = NO
+
+# If the EXTERNAL_GROUPS tag is set to YES all external groups will be listed
+# in the modules index. If set to NO, only the current project's groups will
+# be listed.
+
+EXTERNAL_GROUPS = YES
+
+# The PERL_PATH should be the absolute path and name of the perl script
+# interpreter (i.e. the result of `which perl').
+
+PERL_PATH = /usr/bin/perl
+
+#---------------------------------------------------------------------------
+# Configuration options related to the dot tool
+#---------------------------------------------------------------------------
+
+# If the CLASS_DIAGRAMS tag is set to YES (the default) Doxygen will
+# generate a inheritance diagram (in HTML, RTF and LaTeX) for classes with base
+# or super classes. Setting the tag to NO turns the diagrams off. Note that
+# this option also works with HAVE_DOT disabled, but it is recommended to
+# install and use dot, since it yields more powerful graphs.
+
+CLASS_DIAGRAMS = YES
+
+# You can define message sequence charts within doxygen comments using the \msc
+# command. Doxygen will then run the mscgen tool (see
+# http://www.mcternan.me.uk/mscgen/) to produce the chart and insert it in the
+# documentation. The MSCGEN_PATH tag allows you to specify the directory where
+# the mscgen tool resides. If left empty the tool is assumed to be found in the
+# default search path.
+
+MSCGEN_PATH =
+
+# If set to YES, the inheritance and collaboration graphs will hide
+# inheritance and usage relations if the target is undocumented
+# or is not a class.
+
+HIDE_UNDOC_RELATIONS = YES
+
+# If you set the HAVE_DOT tag to YES then doxygen will assume the dot tool is
+# available from the path. This tool is part of Graphviz, a graph visualization
+# toolkit from AT&T and Lucent Bell Labs. The other options in this section
+# have no effect if this option is set to NO (the default)
+
+HAVE_DOT = NO
+
+# The DOT_NUM_THREADS specifies the number of dot invocations doxygen is
+# allowed to run in parallel. When set to 0 (the default) doxygen will
+# base this on the number of processors available in the system. You can set it
+# explicitly to a value larger than 0 to get control over the balance
+# between CPU load and processing speed.
+
+DOT_NUM_THREADS = 0
+
+# By default doxygen will use the Helvetica font for all dot files that
+# doxygen generates. When you want a differently looking font you can specify
+# the font name using DOT_FONTNAME. You need to make sure dot is able to find
+# the font, which can be done by putting it in a standard location or by setting
+# the DOTFONTPATH environment variable or by setting DOT_FONTPATH to the
+# directory containing the font.
+
+DOT_FONTNAME = Helvetica
+
+# The DOT_FONTSIZE tag can be used to set the size of the font of dot graphs.
+# The default size is 10pt.
+
+DOT_FONTSIZE = 10
+
+# By default doxygen will tell dot to use the Helvetica font.
+# If you specify a different font using DOT_FONTNAME you can use DOT_FONTPATH to
+# set the path where dot can find it.
+
+DOT_FONTPATH =
+
+# If the CLASS_GRAPH and HAVE_DOT tags are set to YES then doxygen
+# will generate a graph for each documented class showing the direct and
+# indirect inheritance relations. Setting this tag to YES will force the
+# CLASS_DIAGRAMS tag to NO.
+
+CLASS_GRAPH = YES
+
+# If the COLLABORATION_GRAPH and HAVE_DOT tags are set to YES then doxygen
+# will generate a graph for each documented class showing the direct and
+# indirect implementation dependencies (inheritance, containment, and
+# class references variables) of the class with other documented classes.
+
+COLLABORATION_GRAPH = YES
+
+# If the GROUP_GRAPHS and HAVE_DOT tags are set to YES then doxygen
+# will generate a graph for groups, showing the direct groups dependencies
+
+GROUP_GRAPHS = YES
+
+# If the UML_LOOK tag is set to YES doxygen will generate inheritance and
+# collaboration diagrams in a style similar to the OMG's Unified Modeling
+# Language.
+
+UML_LOOK = NO
+
+# If set to YES, the inheritance and collaboration graphs will show the
+# relations between templates and their instances.
+
+TEMPLATE_RELATIONS = NO
+
+# If the ENABLE_PREPROCESSING, SEARCH_INCLUDES, INCLUDE_GRAPH, and HAVE_DOT
+# tags are set to YES then doxygen will generate a graph for each documented
+# file showing the direct and indirect include dependencies of the file with
+# other documented files.
+
+INCLUDE_GRAPH = YES
+
+# If the ENABLE_PREPROCESSING, SEARCH_INCLUDES, INCLUDED_BY_GRAPH, and
+# HAVE_DOT tags are set to YES then doxygen will generate a graph for each
+# documented header file showing the documented files that directly or
+# indirectly include this file.
+
+INCLUDED_BY_GRAPH = YES
+
+# If the CALL_GRAPH and HAVE_DOT options are set to YES then
+# doxygen will generate a call dependency graph for every global function
+# or class method. Note that enabling this option will significantly increase
+# the time of a run. So in most cases it will be better to enable call graphs
+# for selected functions only using the \callgraph command.
+
+CALL_GRAPH = NO
+
+# If the CALLER_GRAPH and HAVE_DOT tags are set to YES then
+# doxygen will generate a caller dependency graph for every global function
+# or class method. Note that enabling this option will significantly increase
+# the time of a run. So in most cases it will be better to enable caller
+# graphs for selected functions only using the \callergraph command.
+
+CALLER_GRAPH = NO
+
+# If the GRAPHICAL_HIERARCHY and HAVE_DOT tags are set to YES then doxygen
+# will generate a graphical hierarchy of all classes instead of a textual one.
+
+GRAPHICAL_HIERARCHY = YES
+
+# If the DIRECTORY_GRAPH, SHOW_DIRECTORIES and HAVE_DOT tags are set to YES
+# then doxygen will show the dependencies a directory has on other directories
+# in a graphical way. The dependency relations are determined by the #include
+# relations between the files in the directories.
+
+DIRECTORY_GRAPH = YES
+
+# The DOT_IMAGE_FORMAT tag can be used to set the image format of the images
+# generated by dot. Possible values are svg, png, jpg, or gif.
+# If left blank png will be used. If you choose svg you need to set
+# HTML_FILE_EXTENSION to xhtml in order to make the SVG files
+# visible in IE 9+ (other browsers do not have this requirement).
+
+DOT_IMAGE_FORMAT = png
+
+# If DOT_IMAGE_FORMAT is set to svg, then this option can be set to YES to
+# enable generation of interactive SVG images that allow zooming and panning.
+# Note that this requires a modern browser other than Internet Explorer.
+# Tested and working are Firefox, Chrome, Safari, and Opera. For IE 9+ you
+# need to set HTML_FILE_EXTENSION to xhtml in order to make the SVG files
+# visible. Older versions of IE do not have SVG support.
+
+INTERACTIVE_SVG = NO
+
+# The tag DOT_PATH can be used to specify the path where the dot tool can be
+# found. If left blank, it is assumed the dot tool can be found in the path.
+
+DOT_PATH =
+
+# The DOTFILE_DIRS tag can be used to specify one or more directories that
+# contain dot files that are included in the documentation (see the
+# \dotfile command).
+
+DOTFILE_DIRS =
+
+# The MSCFILE_DIRS tag can be used to specify one or more directories that
+# contain msc files that are included in the documentation (see the
+# \mscfile command).
+
+MSCFILE_DIRS =
+
+# The DOT_GRAPH_MAX_NODES tag can be used to set the maximum number of
+# nodes that will be shown in the graph. If the number of nodes in a graph
+# becomes larger than this value, doxygen will truncate the graph, which is
+# visualized by representing a node as a red box. Note that doxygen if the
+# number of direct children of the root node in a graph is already larger than
+# DOT_GRAPH_MAX_NODES then the graph will not be shown at all. Also note
+# that the size of a graph can be further restricted by MAX_DOT_GRAPH_DEPTH.
+
+DOT_GRAPH_MAX_NODES = 50
+
+# The MAX_DOT_GRAPH_DEPTH tag can be used to set the maximum depth of the
+# graphs generated by dot. A depth value of 3 means that only nodes reachable
+# from the root by following a path via at most 3 edges will be shown. Nodes
+# that lay further from the root node will be omitted. Note that setting this
+# option to 1 or 2 may greatly reduce the computation time needed for large
+# code bases. Also note that the size of a graph can be further restricted by
+# DOT_GRAPH_MAX_NODES. Using a depth of 0 means no depth restriction.
+
+MAX_DOT_GRAPH_DEPTH = 0
+
+# Set the DOT_TRANSPARENT tag to YES to generate images with a transparent
+# background. This is disabled by default, because dot on Windows does not
+# seem to support this out of the box. Warning: Depending on the platform used,
+# enabling this option may lead to badly anti-aliased labels on the edges of
+# a graph (i.e. they become hard to read).
+
+DOT_TRANSPARENT = NO
+
+# Set the DOT_MULTI_TARGETS tag to YES allow dot to generate multiple output
+# files in one run (i.e. multiple -o and -T options on the command line). This
+# makes dot run faster, but since only newer versions of dot (>1.8.10)
+# support this, this feature is disabled by default.
+
+DOT_MULTI_TARGETS = NO
+
+# If the GENERATE_LEGEND tag is set to YES (the default) Doxygen will
+# generate a legend page explaining the meaning of the various boxes and
+# arrows in the dot generated graphs.
+
+GENERATE_LEGEND = YES
+
+# If the DOT_CLEANUP tag is set to YES (the default) Doxygen will
+# remove the intermediate dot files that are used to generate
+# the various graphs.
+
+DOT_CLEANUP = YES
--- a/src/formats.c
+++ b/src/formats.c
@@ -113,34 +113,34 @@
}
static sox_encodings_info_t const s_sox_encodings_info[] = {- {0 , "n/a" , "Unknown or not applicable"},- {0 , "Signed PCM" , "Signed Integer PCM"},- {0 , "Unsigned PCM" , "Unsigned Integer PCM"},- {0 , "F.P. PCM" , "Floating Point PCM"},- {0 , "F.P. PCM" , "Floating Point (text) PCM"},- {0 , "FLAC" , "FLAC"},- {0 , "HCOM" , "HCOM"},- {0 , "WavPack" , "WavPack"},- {0 , "F.P. WavPack" , "Floating Point WavPack"},- {SOX_LOSSY1, "u-law" , "u-law"},- {SOX_LOSSY1, "A-law" , "A-law"},- {SOX_LOSSY1, "G.721 ADPCM" , "G.721 ADPCM"},- {SOX_LOSSY1, "G.723 ADPCM" , "G.723 ADPCM"},- {SOX_LOSSY1, "CL ADPCM (8)" , "CL ADPCM (from 8-bit)"},- {SOX_LOSSY1, "CL ADPCM (16)", "CL ADPCM (from 16-bit)"},- {SOX_LOSSY1, "MS ADPCM" , "MS ADPCM"},- {SOX_LOSSY1, "IMA ADPCM" , "IMA ADPCM"},- {SOX_LOSSY1, "OKI ADPCM" , "OKI ADPCM"},- {SOX_LOSSY1, "DPCM" , "DPCM"},- {0 , "DWVW" , "DWVW"},- {0 , "DWVWN" , "DWVWN"},- {SOX_LOSSY2, "GSM" , "GSM"},- {SOX_LOSSY2, "MPEG audio" , "MPEG audio (layer I, II or III)"},- {SOX_LOSSY2, "Vorbis" , "Vorbis"},- {SOX_LOSSY2, "AMR-WB" , "AMR-WB"},- {SOX_LOSSY2, "AMR-NB" , "AMR-NB"},- {SOX_LOSSY2, "CVSD" , "CVSD"},- {SOX_LOSSY2, "LPC10" , "LPC10"},+ {sox_encodings_none , "n/a" , "Unknown or not applicable"},+ {sox_encodings_none , "Signed PCM" , "Signed Integer PCM"},+ {sox_encodings_none , "Unsigned PCM" , "Unsigned Integer PCM"},+ {sox_encodings_none , "F.P. PCM" , "Floating Point PCM"},+ {sox_encodings_none , "F.P. PCM" , "Floating Point (text) PCM"},+ {sox_encodings_none , "FLAC" , "FLAC"},+ {sox_encodings_none , "HCOM" , "HCOM"},+ {sox_encodings_none , "WavPack" , "WavPack"},+ {sox_encodings_none , "F.P. WavPack" , "Floating Point WavPack"},+ {sox_encodings_lossy1, "u-law" , "u-law"},+ {sox_encodings_lossy1, "A-law" , "A-law"},+ {sox_encodings_lossy1, "G.721 ADPCM" , "G.721 ADPCM"},+ {sox_encodings_lossy1, "G.723 ADPCM" , "G.723 ADPCM"},+ {sox_encodings_lossy1, "CL ADPCM (8)" , "CL ADPCM (from 8-bit)"},+ {sox_encodings_lossy1, "CL ADPCM (16)", "CL ADPCM (from 16-bit)"},+ {sox_encodings_lossy1, "MS ADPCM" , "MS ADPCM"},+ {sox_encodings_lossy1, "IMA ADPCM" , "IMA ADPCM"},+ {sox_encodings_lossy1, "OKI ADPCM" , "OKI ADPCM"},+ {sox_encodings_lossy1, "DPCM" , "DPCM"},+ {sox_encodings_none , "DWVW" , "DWVW"},+ {sox_encodings_none , "DWVWN" , "DWVWN"},+ {sox_encodings_lossy2, "GSM" , "GSM"},+ {sox_encodings_lossy2, "MPEG audio" , "MPEG audio (layer I, II or III)"},+ {sox_encodings_lossy2, "Vorbis" , "Vorbis"},+ {sox_encodings_lossy2, "AMR-WB" , "AMR-WB"},+ {sox_encodings_lossy2, "AMR-NB" , "AMR-NB"},+ {sox_encodings_lossy2, "CVSD" , "CVSD"},+ {sox_encodings_lossy2, "LPC10" , "LPC10"},};
assert_static(array_length(s_sox_encodings_info) == SOX_ENCODINGS,
@@ -197,9 +197,9 @@
void sox_init_encodinginfo(sox_encodinginfo_t * e)
{- e->reverse_bytes = SOX_OPTION_DEFAULT;
- e->reverse_nibbles = SOX_OPTION_DEFAULT;
- e->reverse_bits = SOX_OPTION_DEFAULT;
+ e->reverse_bytes = sox_option_default;
+ e->reverse_nibbles = sox_option_default;
+ e->reverse_bits = sox_option_default;
e->compression = HUGE_VAL;
}
@@ -295,7 +295,7 @@
if (ft->encoding.opposite_endian)
ft->encoding.reverse_bytes = (ft->handler.flags & SOX_FILE_ENDIAN)?
!(ft->handler.flags & SOX_FILE_ENDBIG) != MACHINE_IS_BIGENDIAN : sox_true;
- else if (ft->encoding.reverse_bytes == SOX_OPTION_DEFAULT)
+ else if (ft->encoding.reverse_bytes == sox_option_default)
ft->encoding.reverse_bytes = (ft->handler.flags & SOX_FILE_ENDIAN)?
!(ft->handler.flags & SOX_FILE_ENDBIG) == MACHINE_IS_BIGENDIAN : sox_false;
@@ -306,15 +306,15 @@
if (ft->encoding.reverse_bytes == (sox_option_t)
(!(ft->handler.flags & SOX_FILE_ENDBIG) != MACHINE_IS_BIGENDIAN))
lsx_report("`%s': overriding file-type byte-order", ft->filename);- } else if (ft->encoding.reverse_bytes == SOX_OPTION_YES)
+ } else if (ft->encoding.reverse_bytes == sox_option_yes)
lsx_report("`%s': overriding machine byte-order", ft->filename);- if (ft->encoding.reverse_bits == SOX_OPTION_DEFAULT)
+ if (ft->encoding.reverse_bits == sox_option_default)
ft->encoding.reverse_bits = !!(ft->handler.flags & SOX_FILE_BIT_REV);
else if (ft->encoding.reverse_bits == !(ft->handler.flags & SOX_FILE_BIT_REV))
lsx_report("`%s': overriding file-type bit-order", ft->filename);- if (ft->encoding.reverse_nibbles == SOX_OPTION_DEFAULT)
+ if (ft->encoding.reverse_nibbles == sox_option_default)
ft->encoding.reverse_nibbles = !!(ft->handler.flags & SOX_FILE_NIB_REV);
else
if (ft->encoding.reverse_nibbles == !(ft->handler.flags & SOX_FILE_NIB_REV))
@@ -737,7 +737,7 @@
i = 0;
while ((e = enc_arg(sox_encoding_t)))
while ((s = enc_arg(unsigned)))
- if (!(sox_encodings_info[e].flags & (SOX_LOSSY1 | SOX_LOSSY2)) &&
+ if (!(sox_encodings_info[e].flags & (sox_encodings_lossy1 | sox_encodings_lossy2)) &&
sox_precision(e, s) >= ft->signal.precision && s < ft->encoding.bits_per_sample) {ft->encoding.encoding = e;
ft->encoding.bits_per_sample = s;
--- a/src/getopt.c
+++ b/src/getopt.c
@@ -23,7 +23,7 @@
#include <string.h>
void
-SOX_API lsx_getopt_init(
+LSX_API lsx_getopt_init(
LSX_PARAM_IN int argc, /* Number of arguments in argv */
LSX_PARAM_IN_COUNT(argc) char * const * argv, /* Array of arguments */
LSX_PARAM_IN_Z char const * shortopts, /* Short option characters */
@@ -78,7 +78,7 @@
}
int
-SOX_API lsx_getopt(
+LSX_API lsx_getopt(
LSX_PARAM_INOUT lsx_getopt_t * state)
{int oerr;
--- a/src/sox.c
+++ b/src/sox.c
@@ -133,7 +133,7 @@
LSX_ENUM_ITEM(RG_,album)
{0, 0}};static rg_mode replay_gain_mode = RG_default;
-static sox_option_t show_progress = SOX_OPTION_DEFAULT;
+static sox_option_t show_progress = sox_option_default;
/* Input & output files */
@@ -1502,7 +1502,7 @@
/* If whether to enable the progress display (similar to that of ogg123) has
* not been specified by the user, auto turn on when outputting to an audio
* device: */
- if (show_progress == SOX_OPTION_DEFAULT)
+ if (show_progress == sox_option_default)
show_progress = (ofile->ft->handler.flags & SOX_FILE_DEVICE) != 0 &&
(ofile->ft->handler.flags & SOX_FILE_PHONY) == 0;
@@ -2240,7 +2240,7 @@
break;
case 5:
- if (f->encoding.reverse_bytes != SOX_OPTION_DEFAULT || f->encoding.opposite_endian)
+ if (f->encoding.reverse_bytes != sox_option_default || f->encoding.opposite_endian)
usage("only one endian option per file is allowed"); switch (enum_option(optstate.arg, optstate.lngind, endian_options)) {case ENDIAN_little: f->encoding.reverse_bytes = MACHINE_IS_BIGENDIAN; break;
@@ -2407,7 +2407,7 @@
break;
case 'L': case 'B': case 'x':
- if (f->encoding.reverse_bytes != SOX_OPTION_DEFAULT || f->encoding.opposite_endian)
+ if (f->encoding.reverse_bytes != sox_option_default || f->encoding.opposite_endian)
usage("only one endian option per file is allowed"); switch (c) {case 'L': f->encoding.reverse_bytes = MACHINE_IS_BIGENDIAN; break;
@@ -2415,11 +2415,11 @@
case 'x': f->encoding.opposite_endian = sox_true; break;
}
break;
- case 'X': f->encoding.reverse_bits = SOX_OPTION_YES; break;
- case 'N': f->encoding.reverse_nibbles = SOX_OPTION_YES; break;
+ case 'X': f->encoding.reverse_bits = sox_option_yes; break;
+ case 'N': f->encoding.reverse_nibbles = sox_option_yes; break;
- case 'S': show_progress = SOX_OPTION_YES; break;
- case 'q': show_progress = SOX_OPTION_NO; break;
+ case 'S': show_progress = sox_option_yes; break;
+ case 'q': show_progress = sox_option_no; break;
case 'D': no_dither = sox_true; break;
case 'V':
@@ -2870,10 +2870,10 @@
/* sox_open_read() will call lsx_warn for most errors.
* Rely on that printing something. */
exit(2);
- if (show_progress == SOX_OPTION_DEFAULT &&
+ if (show_progress == sox_option_default &&
(files[j]->ft->handler.flags & SOX_FILE_DEVICE) != 0 &&
(files[j]->ft->handler.flags & SOX_FILE_PHONY) == 0)
- show_progress = SOX_OPTION_YES;
+ show_progress = sox_option_yes;
}
if (replay_gain_mode == RG_default)
--- a/src/sox.h
+++ b/src/sox.h
@@ -8,151 +8,79 @@
* the consequences of using this software.
*/
+/** @file
+Contains the interface exposed to clients of the libSoX library.
+Symbols starting with "sox_" or "SOX_" are part of the public interface for
+libSoX clients (applications that consume libSoX). Symbols starting with
+"lsx_" or "LSX_" are internal use by libSoX and plugins.
+LSX_ and lsx_ symbols should not be used by libSoX-based applications.
+*/
+
#ifndef SOX_H
-#define SOX_H
+#define SOX_H /**< Client API: This macro is defined if sox.h has been included. */
#include <limits.h>
#include <stdarg.h>
#include <stddef.h>
-#define lsx_static_assert(e,f) \
- enum {lsx_static_assert_##f = 1/(e)}-
#if defined(__cplusplus)
extern "C" {#endif
-/* Suppress warnings from use of type long long */
+/* Suppress warnings from use of type long long. */
#if defined __GNUC__
#pragma GCC system_header
#endif
-#if SCHAR_MAX==127 && SCHAR_MIN==(-128)
-typedef signed char sox_int8_t;
-#elif CHAR_MAX==127 && CHAR_MIN==(-128)
-typedef char sox_int8_t;
-#else
-#error Unable to determine an appropriate definition for sox_int8_t.
-#endif
-lsx_static_assert(sizeof(sox_int8_t)==1, sox_int8_size);
+/*****************************************************************************
+API decoration macros:
+Mostly for documentation purposes. For some compilers, decorations also affect
+code generation, influence compiler warnings or activate compiler
+optimizations.
+*****************************************************************************/
-#if UCHAR_MAX==0xff
-typedef unsigned char sox_uint8_t;
-#elif CHAR_MAX==0xff && CHAR_MIN==0
-typedef char sox_uint8_t;
-#else
-#error Unable to determine an appropriate definition for sox_uint8_t.
-#endif
-lsx_static_assert(sizeof(sox_uint8_t)==1, sox_uint8_size);
-
-#if SHRT_MAX==32767 && SHRT_MIN==(-32768)
-typedef short sox_int16_t;
-#elif INT_MAX==32767 && INT_MIN==(-32768)
-typedef int sox_int16_t;
-#else
-#error Unable to determine an appropriate definition for sox_int16_t.
-#endif
-lsx_static_assert(sizeof(sox_int16_t)==2, sox_int16_size);
-
-#if USHRT_MAX==0xffff
-typedef unsigned short sox_uint16_t;
-#elif UINT_MAX==0xffff
-typedef unsigned int sox_uint16_t;
-#else
-#error Unable to determine an appropriate definition for sox_uint16_t.
-#endif
-lsx_static_assert(sizeof(sox_uint16_t)==2, sox_uint16_size);
-
-#if INT_MAX==2147483647 && INT_MIN==(-2147483647-1)
-typedef int sox_int32_t;
-#elif LONG_MAX==2147483647 && LONG_MIN==(-2147483647-1)
-typedef long sox_int32_t;
-#else
-#error Unable to determine an appropriate definition for sox_int32_t.
-#endif
-lsx_static_assert(sizeof(sox_int32_t)==4, sox_int32_size);
-
-#if UINT_MAX==0xffffffff
-typedef unsigned int sox_uint32_t;
-#elif ULONG_MAX==0xffffffff
-typedef unsigned long sox_uint32_t;
-#else
-#error Unable to determine an appropriate definition for sox_uint32_t.
-#endif
-lsx_static_assert(sizeof(sox_uint32_t)==4, sox_uint32_size);
-
-#if LONG_MAX==9223372036854775807 && LONG_MIN==(-9223372036854775807-1)
-typedef long sox_int64_t;
-#elif defined(_MSC_VER)
-typedef __int64 sox_int64_t;
-#else
-typedef long long sox_int64_t;
-#endif
-lsx_static_assert(sizeof(sox_int64_t)==8, sox_int64_size);
-
-#if ULONG_MAX==0xffffffffffffffff
-typedef unsigned long sox_uint64_t;
-#elif defined(_MSC_VER)
-typedef unsigned __int64 sox_uint64_t;
-#else
-typedef unsigned long long sox_uint64_t;
-#endif
-lsx_static_assert(sizeof(sox_uint64_t)==8, sox_uint64_size);
-
-typedef sox_int32_t sox_int24_t; /* sox_int24_t == sox_int32_t (beware of the extra byte) */
-typedef sox_uint32_t sox_uint24_t; /* sox_uint24_t == sox_uint32_t (beware of the extra byte) */
-
-/* The following is the API version of libSoX. It is not meant
- * to follow the version number of SoX but it has historically.
- * Please do not count on these numbers being in sync. */
-#define SOX_LIB_VERSION(a,b,c) (((a) << 16) + ((b) << 8) + (c))
-#define SOX_LIB_VERSION_CODE SOX_LIB_VERSION(14, 4, 0)
-
-/* SOX_API: Attribute required on all functions declared by SoX and on all
- * function pointer types used by SoX. */
+/**
+Plugins API:
+Attribute required on all functions exported by libSoX and on all function
+pointer types used by the libSoX API.
+*/
#ifdef __GNUC__
-#define SOX_API __attribute__ ((cdecl))
+#define LSX_API __attribute__ ((cdecl)) /* libSoX function */
#elif _MSC_VER
-#define SOX_API __cdecl
+#define LSX_API __cdecl /* libSoX function */
#else
-#define SOX_API
+#define LSX_API /* libSoX function */
#endif
-/* LSX_USE_VAR(x): Expression that "uses" a potentially-unused variable to
- * avoid compiler warnings (i.e. for macro-generated code). */
-#ifdef _PREFAST_
-/* During static analysis, initialize unused variables to 0. */
-#define LSX_USE_VAR(x) ((void)(x=0))
-#else
-#define LSX_USE_VAR(x) ((void)(x))
-#endif
-
-/*
- * API decorations:
- * Mostly for documentation purposes. For some compilers, decorations also
- * influence compiler warnings or activate compiler optimizations.
- */
-
-/* LSX_UNUSED: Attribute applied to a parameter or local variable to suppress
- * warnings about the variable being unused (i.e. for macro-generated code). */
+/**
+Plugins API:
+Attribute applied to a parameter or local variable to suppress warnings about
+the variable being unused (especially in macro-generated code).
+*/
#ifdef __GNUC__
-#define LSX_UNUSED __attribute__ ((unused))
+#define LSX_UNUSED __attribute__ ((unused)) /* Parameter or local variable is intentionally unused. */
#else
-#define LSX_UNUSED
+#define LSX_UNUSED /* Parameter or local variable is intentionally unused. */
#endif
-/* LSX_PRINTF12: Attribute applied to a function to indicate that it requires
- * a printf-style format string for arg1 and that printf parameters start at
- * arg2. */
+/**
+Plugins API:
+LSX_PRINTF12: Attribute applied to a function to indicate that it requires
+a printf-style format string for arg1 and that printf parameters start at
+arg2.
+*/
#ifdef __GNUC__
-#define LSX_PRINTF12 __attribute__ ((format (printf, 1, 2)))
+#define LSX_PRINTF12 __attribute__ ((format (printf, 1, 2))) /* Function has printf-style arguments. */
#else
-#define LSX_PRINTF12
+#define LSX_PRINTF12 /* Function has printf-style arguments. */
#endif
-/* LSX_RETURN_PURE: Attribute applied to a function to indicate that it has no
- * side effects and depends only its input parameters and global memory. If
- * called repeatedly, it returns the same result each time. */
+/**
+Plugins API:
+Attribute applied to a function to indicate that it has no side effects and
+depends only its input parameters and global memory. If called repeatedly, it
+returns the same result each time.
+*/
#ifdef __GNUC__
#define LSX_RETURN_PURE __attribute__ ((pure)) /* Function is pure. */
#else
@@ -159,8 +87,11 @@
#define LSX_RETURN_PURE /* Function is pure. */
#endif
-/* LSX_RETURN_VALID: Attribute applied to a function to indicate that the
- * return value is always a pointer to a valid object (never NULL). */
+/**
+Plugins API:
+Attribute applied to a function to indicate that the
+return value is always a pointer to a valid object (never NULL).
+*/
#ifdef _Ret_
#define LSX_RETURN_VALID _Ret_ /* Function always returns a valid object (never NULL). */
#else
@@ -167,8 +98,11 @@
#define LSX_RETURN_VALID /* Function always returns a valid object (never NULL). */
#endif
-/* LSX_RETURN_ARRAY: Attribute applied to a function to indicate that the
- * return value is always a pointer to a valid array (never NULL). */
+/**
+Plugins API:
+Attribute applied to a function to indicate that the return value is always a
+pointer to a valid array (never NULL).
+*/
#ifdef _Ret_valid_
#define LSX_RETURN_ARRAY _Ret_valid_ /* Function always returns a valid array (never NULL). */
#else
@@ -175,9 +109,11 @@
#define LSX_RETURN_ARRAY /* Function always returns a valid array (never NULL). */
#endif
-/* LSX_RETURN_VALID_Z: Attribute applied to a function to indicate that the
- * return value is always a pointer to a valid 0-terminated array (never
- * NULL). */
+/**
+Plugins API:
+Attribute applied to a function to indicate that the return value is always a
+pointer to a valid 0-terminated array (never NULL).
+*/
#ifdef _Ret_z_
#define LSX_RETURN_VALID_Z _Ret_z_ /* Function always returns a 0-terminated array (never NULL). */
#else
@@ -184,8 +120,11 @@
#define LSX_RETURN_VALID_Z /* Function always returns a 0-terminated array (never NULL). */
#endif
-/* LSX_RETURN_OPT: Attribute applied to a function to indicate that the
- * returned pointer may be null. */
+/**
+Plugins API:
+Attribute applied to a function to indicate that the returned pointer may be
+null.
+*/
#ifdef _Ret_opt_
#define LSX_RETURN_OPT _Ret_opt_ /* Function may return NULL. */
#else
@@ -192,9 +131,11 @@
#define LSX_RETURN_OPT /* Function may return NULL. */
#endif
-/* LSX_PARAM_IN: Attribute applied to a parameter to indicate that the
- * parameter is a valid pointer to one const element of the pointed-to type
- * (never NULL). */
+/**
+Plugins API:
+Attribute applied to a parameter to indicate that the parameter is a valid
+pointer to one const element of the pointed-to type (never NULL).
+*/
#ifdef _In_
#define LSX_PARAM_IN _In_ /* Required const pointer to a valid object (never NULL). */
#else
@@ -201,8 +142,11 @@
#define LSX_PARAM_IN /* Required const pointer to a valid object (never NULL). */
#endif
-/* LSX_PARAM_IN_Z: Attribute applied to a parameter to indicate that the
- * parameter is a valid pointer to a const 0-terminated string (never NULL). */
+/**
+Plugins API:
+Attribute applied to a parameter to indicate that the parameter is a valid
+pointer to a const 0-terminated string (never NULL).
+*/
#ifdef _In_z_
#define LSX_PARAM_IN_Z _In_z_ /* Required const pointer to 0-terminated string (never NULL). */
#else
@@ -209,8 +153,11 @@
#define LSX_PARAM_IN_Z /* Required const pointer to 0-terminated string (never NULL). */
#endif
-/* LSX_PARAM_IN_PRINTF: Attribute applied to a parameter to indicate that the
- * parameter is a const pointer to a 0-terminated printf format string. */
+/**
+Plugins API:
+Attribute applied to a parameter to indicate that the parameter is a const
+pointer to a 0-terminated printf format string.
+*/
#ifdef _Printf_format_string_
#define LSX_PARAM_IN_PRINTF _Printf_format_string_ /* Required const pointer to 0-terminated printf format string (never NULL). */
#else
@@ -217,9 +164,13 @@
#define LSX_PARAM_IN_PRINTF /* Required const pointer to 0-terminated printf format string (never NULL). */
#endif
-/* LSX_PARAM_IN_COUNT(len): Attribute applied to a parameter to indicate that
- * the parameter is a valid pointer to (len) const elements of the pointed-to
- * type, where (len) is the name of another parameter. */
+/**
+Plugins API:
+Attribute applied to a parameter to indicate that the parameter is a valid
+pointer to (len) const initialized elements of the pointed-to type, where
+(len) is the name of another parameter.
+@param len The parameter that contains the number of elements in the array.
+*/
#ifdef _In_count_
#define LSX_PARAM_IN_COUNT(len) _In_count_(len) /* Required const pointer to (len) valid objects (never NULL). */
#else
@@ -226,9 +177,13 @@
#define LSX_PARAM_IN_COUNT(len) /* Required const pointer to (len) valid objects (never NULL). */
#endif
-/* LSX_PARAM_IN_BYTECOUNT(len): Attribute applied to a parameter to indicate that
- * the parameter is a valid pointer to (len) bytes of initialized data, where
- * (len) is the name of another parameter. */
+/**
+Plugins API:
+Attribute applied to a parameter to indicate that the parameter is a valid
+pointer to (len) const bytes of initialized data, where (len) is the name of
+another parameter.
+@param len The parameter that contains the number of bytes in the array.
+*/
#ifdef _In_bytecount_
#define LSX_PARAM_IN_BYTECOUNT(len) _In_bytecount_(len) /* Required const pointer to (len) bytes of data (never NULL). */
#else
@@ -235,9 +190,11 @@
#define LSX_PARAM_IN_BYTECOUNT(len) /* Required const pointer to (len) bytes of data (never NULL). */
#endif
-/* LSX_PARAM_IN_OPT: Attribute applied to a parameter to indicate that the
- * parameter is either NULL or a valid pointer to one const element of the
- * pointed-to type. */
+/**
+Plugins API:
+Attribute applied to a parameter to indicate that the parameter is either NULL
+or a valid pointer to one const element of the pointed-to type.
+*/
#ifdef _In_opt_
#define LSX_PARAM_IN_OPT _In_opt_ /* Optional const pointer to a valid object (may be NULL). */
#else
@@ -244,8 +201,11 @@
#define LSX_PARAM_IN_OPT /* Optional const pointer to a valid object (may be NULL). */
#endif
-/* LSX_PARAM_IN_OPT_Z: Attribute applied to a parameter to indicate that the
- * parameter is either NULL or a valid pointer to a const 0-terminated string. */
+/**
+Plugins API:
+Attribute applied to a parameter to indicate that the parameter is either NULL
+or a valid pointer to a const 0-terminated string.
+*/
#ifdef _In_opt_z_
#define LSX_PARAM_IN_OPT_Z _In_opt_z_ /* Optional const pointer to 0-terminated string (may be NULL). */
#else
@@ -252,9 +212,12 @@
#define LSX_PARAM_IN_OPT_Z /* Optional const pointer to 0-terminated string (may be NULL). */
#endif
-/* LSX_PARAM_INOUT: Attribute applied to a parameter to indicate that the
- * parameter is a valid pointer to one initialized element of the pointed-to
- * type (never NULL). The function may modify the element. */
+/**
+Plugins API:
+Attribute applied to a parameter to indicate that the parameter is a valid
+pointer to one initialized element of the pointed-to type (never NULL). The
+function may modify the element.
+*/
#ifdef _Inout_
#define LSX_PARAM_INOUT _Inout_ /* Required pointer to a valid object (never NULL). */
#else
@@ -261,9 +224,13 @@
#define LSX_PARAM_INOUT /* Required pointer to a valid object (never NULL). */
#endif
-/* LSX_PARAM_INOUT_COUNT(len): Attribute applied to a parameter to indicate
- * that the parameter is a valid pointer to (len) initialized elements of the
- * pointed-to type (never NULL). The function may modify the elements. */
+/**
+Plugins API:
+Attribute applied to a parameter to indicate that the parameter is a valid
+pointer to (len) initialized elements of the pointed-to type (never NULL). The
+function may modify the elements.
+@param len The parameter that contains the number of elements in the array.
+*/
#ifdef _Inout_count_x_
#define LSX_PARAM_INOUT_COUNT(len) _Inout_count_x_(len) /* Required pointer to (len) valid objects (never NULL). */
#else
@@ -270,9 +237,12 @@
#define LSX_PARAM_INOUT_COUNT(len) /* Required pointer to (len) valid objects (never NULL). */
#endif
-/* LSX_PARAM_OUT: Attribute applied to a parameter to indicate that the
- * parameter is a valid pointer to memory sufficient for one element of the
- * pointed-to type (never NULL). The function will initialize the element. */
+/**
+Plugins API:
+Attribute applied to a parameter to indicate that the parameter is a valid
+pointer to memory sufficient for one element of the pointed-to type (never
+NULL). The function will initialize the element.
+*/
#ifdef _Out_
#define LSX_PARAM_OUT _Out_ /* Required pointer to an object to be initialized (never NULL). */
#else
@@ -279,10 +249,14 @@
#define LSX_PARAM_OUT /* Required pointer to an object to be initialized (never NULL). */
#endif
-/* LSX_PARAM_OUT_BYTECAP(len): Attribute applied to a parameter to indicate
- * that the parameter is a valid pointer to memory sufficient for (len) bytes
- * of data (never NULL), where (len) is the name of another parameter. The
- * function may write up to len bytes of data to this memory. */
+/**
+Plugins API:
+Attribute applied to a parameter to indicate that the parameter is a valid
+pointer to memory sufficient for (len) bytes of data (never NULL), where (len)
+is the name of another parameter. The function may write up to len bytes of
+data to this memory.
+@param len The parameter that contains the number of bytes in the array.
+*/
#ifdef _Out_bytecap_
#define LSX_PARAM_OUT_BYTECAP(len) _Out_bytecap_(len) /* Required pointer to writable buffer with room for len bytes. */
#else
@@ -289,13 +263,18 @@
#define LSX_PARAM_OUT_BYTECAP(len) /* Required pointer to writable buffer with room for len bytes. */
#endif
-/* LSX_PARAM_OUT_CAP_POST_COUNT(len,filled): Attribute applied to a parameter
- * to indicate that the parameter is a valid pointer to memory sufficient for
- * (len) elements of the pointed-to type (never NULL), where (len) is the name
- * of another parameter. On return, (filled) elements will have been
- * initialized, where (filled) is either the dereference of another pointer
- * parameter (i.e. "*written") or the "return" parameter (indicating that the
- * function returns the number of elements written). */
+/**
+Plugins API:
+Attribute applied to a parameter to indicate that the parameter is a valid
+pointer to memory sufficient for (len) elements of the pointed-to type (never
+NULL), where (len) is the name of another parameter. On return, (filled)
+elements will have been initialized, where (filled) is either the dereference
+of another pointer parameter (for example "*written") or the "return"
+parameter (indicating that the function returns the number of elements
+written).
+@param len The parameter that contains the number of elements in the array.
+@param filled The dereference of the parameter that receives the number of elements written to the array, or "return" if the value is returned.
+*/
#ifdef _Out_cap_post_count_
#define LSX_PARAM_OUT_CAP_POST_COUNT(len,filled) _Out_cap_post_count_(len,filled) /* Required pointer to buffer for (len) elements (never NULL); on return, (filled) elements will have been initialized. */
#else
@@ -302,14 +281,18 @@
#define LSX_PARAM_OUT_CAP_POST_COUNT(len,filled) /* Required pointer to buffer for (len) elements (never NULL); on return, (filled) elements will have been initialized. */
#endif
-/* LSX_PARAM_OUT_Z_CAP_POST_COUNT(len,filled): Attribute applied to a parameter
- * to indicate that the parameter is a valid pointer to memory sufficient for
- * (len) elements of the pointed-to type (never NULL), where (len) is the name
- * of another parameter. On return, (filled+1) elements will have been
- * initialized, with the last element having been initialized to 0, where
- * (filled) is either the dereference of another pointer parameter (i.e.
- * "*written") or the "return" parameter (indicating that the function returns
- * the number of elements written). */
+/**
+Plugins API:
+Attribute applied to a parameter to indicate that the parameter is a valid
+pointer to memory sufficient for (len) elements of the pointed-to type (never
+NULL), where (len) is the name of another parameter. On return, (filled+1)
+elements will have been initialized, with the last element having been
+initialized to 0, where (filled) is either the dereference of another pointer
+parameter (for example, "*written") or the "return" parameter (indicating that
+the function returns the number of elements written).
+@param len The parameter that contains the number of elements in the array.
+@param filled The dereference of the parameter that receives the number of elements written to the array (not counting the terminating null), or "return" if the value is returned.
+*/
#ifdef _Out_z_cap_post_count_
#define LSX_PARAM_OUT_Z_CAP_POST_COUNT(len,filled) _Out_z_cap_post_count_(len,filled) /* Required pointer to buffer for (len) elements (never NULL); on return, (filled+1) elements will have been initialized, and the array will be 0-terminated. */
#else
@@ -316,9 +299,12 @@
#define LSX_PARAM_OUT_Z_CAP_POST_COUNT(len,filled) /* Required pointer to buffer for (len) elements (never NULL); on return, (filled+1) elements will have been initialized, and the array will be 0-terminated. */
#endif
-/* LSX_PARAM_OUT_OPT: Attribute applied to a parameter to indicate that the
- * parameter is either NULL or a valid pointer to memory sufficient for one
- * element of the pointed-to type. The function will initialize the element. */
+/**
+Plugins API:
+Attribute applied to a parameter to indicate that the parameter is either NULL
+or a valid pointer to memory sufficient for one element of the pointed-to
+type. The function will initialize the element.
+*/
#ifdef _Out_opt_
#define LSX_PARAM_OUT_OPT _Out_opt_ /* Optional pointer to an object to be initialized (may be NULL). */
#else
@@ -325,9 +311,12 @@
#define LSX_PARAM_OUT_OPT /* Optional pointer to an object to be initialized (may be NULL). */
#endif
-/* LSX_PARAM_DEREF_PRE_MAYBENULL: Attribute applied to a parameter to indicate
- * that the parameter is a valid pointer (never NULL) to another pointer which
- * may be NULL when the function is invoked. */
+/**
+Plugins API:
+Attribute applied to a parameter to indicate that the parameter is a valid
+pointer (never NULL) to another pointer which may be NULL when the function is
+invoked.
+*/
#ifdef _Deref_pre_maybenull_
#define LSX_PARAM_DEREF_PRE_MAYBENULL _Deref_pre_maybenull_ /* Required pointer (never NULL) to another pointer (may be NULL). */
#else
@@ -334,9 +323,12 @@
#define LSX_PARAM_DEREF_PRE_MAYBENULL /* Required pointer (never NULL) to another pointer (may be NULL). */
#endif
-/* LSX_PARAM_DEREF_POST_NULL: Attribute applied to a parameter to indicate
- * that the parameter is a valid pointer (never NULL) to another pointer which
- * will be NULL when the function returns. */
+/**
+Plugins API:
+Attribute applied to a parameter to indicate that the parameter is a valid
+pointer (never NULL) to another pointer which will be NULL when the function
+returns.
+*/
#ifdef _Deref_post_null_
#define LSX_PARAM_DEREF_POST_NULL _Deref_post_null_ /* Required pointer (never NULL) to another pointer, which will be NULL on exit. */
#else
@@ -343,9 +335,12 @@
#define LSX_PARAM_DEREF_POST_NULL /* Required pointer (never NULL) to another pointer, which will be NULL on exit. */
#endif
-/* LSX_PARAM_DEREF_POST_NOTNULL: Attribute applied to a parameter to indicate
- * that the parameter is a valid pointer (never NULL) to another pointer which
- * will be non-NULL when the function returns. */
+/**
+Plugins API:
+Attribute applied to a parameter to indicate that the parameter is a valid
+pointer (never NULL) to another pointer which will be non-NULL when the
+function returns.
+*/
#ifdef _Deref_post_notnull_
#define LSX_PARAM_DEREF_POST_NOTNULL _Deref_post_notnull_ /* Required pointer (never NULL) to another pointer, which will be valid (not NULL) on exit. */
#else
@@ -352,73 +347,398 @@
#define LSX_PARAM_DEREF_POST_NOTNULL /* Required pointer (never NULL) to another pointer, which will be valid (not NULL) on exit. */
#endif
-/* Returns version number string, i.e. "14.4.0". */
-LSX_RETURN_VALID_Z LSX_RETURN_PURE const char *
-SOX_API sox_version(void);
+/**
+Plugins API:
+Expression that "uses" a potentially-unused variable to avoid compiler
+warnings (especially in macro-generated code).
+*/
+#ifdef _PREFAST_
+#define LSX_USE_VAR(x) ((void)(x=0)) /* During static analysis, initialize unused variables to 0. */
+#else
+#define LSX_USE_VAR(x) ((void)(x)) /* Parameter or variable is intentionally unused. */
+#endif
-/* Flags indicating whether optional features are present in this build of SoX */
+/**
+Plugins API:
+Compile-time assertion. Causes a compile error if the expression is false.
+@param e The expression to test. If expression is false, compilation will fail.
+@param f A unique identifier for the test, for example foo_must_not_be_zero.
+*/
+#define lsx_static_assert(e,f) enum {lsx_static_assert_##f = 1/((e) ? 1 : 0)}+
+/*****************************************************************************
+Basic typedefs:
+*****************************************************************************/
+
+/**
+Client API:
+Signed twos-complement 8-bit type. Typically defined as signed char.
+*/
+#if SCHAR_MAX==127 && SCHAR_MIN==(-128)
+typedef signed char sox_int8_t;
+#elif CHAR_MAX==127 && CHAR_MIN==(-128)
+typedef char sox_int8_t;
+#else
+#error Unable to determine an appropriate definition for sox_int8_t.
+#endif
+
+/**
+Client API:
+Unsigned 8-bit type. Typically defined as unsigned char.
+*/
+#if UCHAR_MAX==0xff
+typedef unsigned char sox_uint8_t;
+#elif CHAR_MAX==0xff && CHAR_MIN==0
+typedef char sox_uint8_t;
+#else
+#error Unable to determine an appropriate definition for sox_uint8_t.
+#endif
+
+/**
+Client API:
+Signed twos-complement 16-bit type. Typically defined as short.
+*/
+#if SHRT_MAX==32767 && SHRT_MIN==(-32768)
+typedef short sox_int16_t;
+#elif INT_MAX==32767 && INT_MIN==(-32768)
+typedef int sox_int16_t;
+#else
+#error Unable to determine an appropriate definition for sox_int16_t.
+#endif
+
+/**
+Client API:
+Unsigned 16-bit type. Typically defined as unsigned short.
+*/
+#if USHRT_MAX==0xffff
+typedef unsigned short sox_uint16_t;
+#elif UINT_MAX==0xffff
+typedef unsigned int sox_uint16_t;
+#else
+#error Unable to determine an appropriate definition for sox_uint16_t.
+#endif
+
+/**
+Client API:
+Signed twos-complement 32-bit type. Typically defined as int.
+*/
+#if INT_MAX==2147483647 && INT_MIN==(-2147483647-1)
+typedef int sox_int32_t;
+#elif LONG_MAX==2147483647 && LONG_MIN==(-2147483647-1)
+typedef long sox_int32_t;
+#else
+#error Unable to determine an appropriate definition for sox_int32_t.
+#endif
+
+/**
+Client API:
+Unsigned 32-bit type. Typically defined as unsigned int.
+*/
+#if UINT_MAX==0xffffffff
+typedef unsigned int sox_uint32_t;
+#elif ULONG_MAX==0xffffffff
+typedef unsigned long sox_uint32_t;
+#else
+#error Unable to determine an appropriate definition for sox_uint32_t.
+#endif
+
+/**
+Client API:
+Signed twos-complement 64-bit type. Typically defined as long or long long.
+*/
+#if LONG_MAX==9223372036854775807 && LONG_MIN==(-9223372036854775807-1)
+typedef long sox_int64_t;
+#elif defined(_MSC_VER)
+typedef __int64 sox_int64_t;
+#else
+typedef long long sox_int64_t;
+#endif
+
+/**
+Client API:
+Unsigned 64-bit type. Typically defined as unsigned long or unsigned long long.
+*/
+#if ULONG_MAX==0xffffffffffffffff
+typedef unsigned long sox_uint64_t;
+#elif defined(_MSC_VER)
+typedef unsigned __int64 sox_uint64_t;
+#else
+typedef unsigned long long sox_uint64_t;
+#endif
+
+#ifndef _DOXYGEN_
+lsx_static_assert(sizeof(sox_int8_t)==1, sox_int8_size);
+lsx_static_assert(sizeof(sox_uint8_t)==1, sox_uint8_size);
+lsx_static_assert(sizeof(sox_int16_t)==2, sox_int16_size);
+lsx_static_assert(sizeof(sox_uint16_t)==2, sox_uint16_size);
+lsx_static_assert(sizeof(sox_int32_t)==4, sox_int32_size);
+lsx_static_assert(sizeof(sox_uint32_t)==4, sox_uint32_size);
+lsx_static_assert(sizeof(sox_int64_t)==8, sox_int64_size);
+lsx_static_assert(sizeof(sox_uint64_t)==8, sox_uint64_size);
+#endif
+
+/**
+Client API:
+Alias for sox_int32_t (beware of the extra byte).
+*/
+typedef sox_int32_t sox_int24_t;
+
+/**
+Client API:
+Alias for sox_uint32_t (beware of the extra byte).
+*/
+typedef sox_uint32_t sox_uint24_t;
+
+/**
+Client API:
+Native SoX audio sample type (alias for sox_int32_t).
+*/
+typedef sox_int32_t sox_sample_t;
+
+/**
+Client API:
+Samples per second is stored as a double.
+*/
+typedef double sox_rate_t;
+
+/**
+Client API:
+File's metadata, access via sox_*_comments functions.
+*/
+typedef char * * sox_comments_t;
+
+/*****************************************************************************
+Enumerations:
+*****************************************************************************/
+
+/**
+Client API:
+Boolean type, assignment (but not necessarily binary) compatible with C++ bool.
+*/
+typedef enum sox_bool {+ sox_false, /**< False = 0. */
+ sox_true /**< True = 1. */
+} sox_bool;
+
+/**
+Client API:
+no, yes, or default (default usually implies some kind of auto-detect logic).
+*/
+typedef enum sox_option_t {+ sox_option_no, /**< Option specified as no = 0. */
+ sox_option_yes, /**< Option specified as yes = 1. */
+ sox_option_default /**< Option unspecified = 2. */
+} sox_option_t;
+
+/**
+Client API:
+The libSoX-specific error codes.
+libSoX functions may return these codes or others that map from errno codes.
+*/
+enum sox_error_t {+ SOX_SUCCESS = 0, /**< Function succeeded = 0 */
+ SOX_EOF = -1, /**< End Of File or other error = -1 */
+ SOX_EHDR = 2000, /**< Invalid Audio Header = 2000 */
+ SOX_EFMT, /**< Unsupported data format = 2001 */
+ SOX_ENOMEM, /**< Can't alloc memory = 2002 */
+ SOX_EPERM, /**< Operation not permitted = 2003 */
+ SOX_ENOTSUP, /**< Operation not supported = 2004 */
+ SOX_EINVAL /**< Invalid argument = 2005 */
+};
+
+/**
+Client API:
+Flags indicating whether optional features are present in this build of libSoX.
+*/
typedef enum sox_version_flags_t {- sox_version_none = 0,
- sox_version_have_popen = 1,
- sox_version_have_magic = 2,
- sox_version_have_threads = 4,
- sox_version_have_memopen = 8
+ sox_version_none = 0, /**< No special features = 0. */
+ sox_version_have_popen = 1, /**< popen = 1. */
+ sox_version_have_magic = 2, /**< magic = 2. */
+ sox_version_have_threads = 4, /**< threads = 4. */
+ sox_version_have_memopen = 8 /**< memopen = 8. */
} sox_version_flags_t;
-/* Information about this build of SoX */
-typedef struct sox_version_info_t {- size_t size; /* structure size = sizeof(sox_version_info_t) */
- sox_version_flags_t flags; /* feature flags = popen | magic | threads | memopen */
- sox_uint32_t version_code; /* version number = SOX_LIB_VERSION_CODE, i.e. 0x140400 */
- const char * version; /* version string = sox_version(), i.e. "14.4.0" */
- const char * version_extra;/* version extra info or null = "PACKAGE_EXTRA", i.e. "beta" */
- const char * time; /* build time = "__DATE__ __TIME__", i.e. "Jan 7 2010 03:31:50" */
- const char * distro; /* distro or null = "DISTRO", i.e. "Debian" */
- const char * compiler; /* compiler info or null, i.e. "msvc 160040219" */
- const char * arch; /* arch, i.e. "1248 48 44 L OMP" */
- /* new info should be added at the end for version backwards-compatibility. */
-} sox_version_info_t;
+/**
+Client API:
+Format of sample data.
+*/
+typedef enum sox_encoding_t {+ SOX_ENCODING_UNKNOWN , /**< encoding has not yet been determined */
-/* Returns information about this build of libsox. */
-LSX_RETURN_VALID LSX_RETURN_PURE sox_version_info_t const *
-SOX_API sox_version_info(void);
+ SOX_ENCODING_SIGN2 , /**< signed linear 2's comp: Mac */
+ SOX_ENCODING_UNSIGNED , /**< unsigned linear: Sound Blaster */
+ SOX_ENCODING_FLOAT , /**< floating point (binary format) */
+ SOX_ENCODING_FLOAT_TEXT, /**< floating point (text format) */
+ SOX_ENCODING_FLAC , /**< FLAC compression */
+ SOX_ENCODING_HCOM , /**< Mac FSSD files with Huffman compression */
+ SOX_ENCODING_WAVPACK , /**< WavPack with integer samples */
+ SOX_ENCODING_WAVPACKF , /**< WavPack with float samples */
+ SOX_ENCODING_ULAW , /**< u-law signed logs: US telephony, SPARC */
+ SOX_ENCODING_ALAW , /**< A-law signed logs: non-US telephony, Psion */
+ SOX_ENCODING_G721 , /**< G.721 4-bit ADPCM */
+ SOX_ENCODING_G723 , /**< G.723 3 or 5 bit ADPCM */
+ SOX_ENCODING_CL_ADPCM , /**< Creative Labs 8 --> 2,3,4 bit Compressed PCM */
+ SOX_ENCODING_CL_ADPCM16, /**< Creative Labs 16 --> 4 bit Compressed PCM */
+ SOX_ENCODING_MS_ADPCM , /**< Microsoft Compressed PCM */
+ SOX_ENCODING_IMA_ADPCM , /**< IMA Compressed PCM */
+ SOX_ENCODING_OKI_ADPCM , /**< Dialogic/OKI Compressed PCM */
+ SOX_ENCODING_DPCM , /**< Differential PCM: Fasttracker 2 (xi) */
+ SOX_ENCODING_DWVW , /**< Delta Width Variable Word */
+ SOX_ENCODING_DWVWN , /**< Delta Width Variable Word N-bit */
+ SOX_ENCODING_GSM , /**< GSM 6.10 33byte frame lossy compression */
+ SOX_ENCODING_MP3 , /**< MP3 compression */
+ SOX_ENCODING_VORBIS , /**< Vorbis compression */
+ SOX_ENCODING_AMR_WB , /**< AMR-WB compression */
+ SOX_ENCODING_AMR_NB , /**< AMR-NB compression */
+ SOX_ENCODING_CVSD , /**< Continuously Variable Slope Delta modulation */
+ SOX_ENCODING_LPC10 , /**< Linear Predictive Coding */
-/* libSoX-specific error codes. The rest directly map from errno. */
-enum sox_error_t {- SOX_SUCCESS = 0, /* Function succeeded = 0 */
- SOX_EOF = -1, /* End Of File or other error = -1 */
- SOX_EHDR = 2000, /* Invalid Audio Header */
- SOX_EFMT, /* Unsupported data format */
- SOX_ENOMEM, /* Can't alloc memory */
- SOX_EPERM, /* Operation not permitted */
- SOX_ENOTSUP, /* Operation not supported */
- SOX_EINVAL /* Invalid argument */
+ SOX_ENCODINGS /**< End of list marker */
+} sox_encoding_t;
+
+/**
+Client API:
+Flags for sox_encodings_info_t: lossless/lossy1/lossy2.
+*/
+typedef enum sox_encodings_flags_t {+ sox_encodings_none = 0, /**< no flags specified (implies lossless encoding) = 0. */
+ sox_encodings_lossy1 = 1, /**< encode, decode: lossy once = 1. */
+ sox_encodings_lossy2 = 2 /**< encode, decode, encode, decode: lossy twice = 2. */
+} sox_encodings_flags_t;
+
+/**
+Client API:
+Type of plot.
+*/
+typedef enum sox_plot_t {+ sox_plot_off, /**< No plot = 0. */
+ sox_plot_octave, /**< Octave plot = 1. */
+ sox_plot_gnuplot, /**< Gnuplot plot = 2. */
+ sox_plot_data /**< Plot data = 3. */
+} sox_plot_t;
+
+/**
+Client API:
+Loop modes: upper 4 bits mask the loop blass, lower 4 bits describe
+the loop behaviour, for example single shot, bidirectional etc.
+*/
+enum sox_loop_flags_t {+ sox_loop_none = 0, /**< single-shot = 0 */
+ sox_loop_forward = 1, /**< forward loop = 1 */
+ sox_loop_forward_back = 2, /**< forward/back loop = 2 */
+ sox_loop_8 = 32, /**< 8 loops (??) = 32 */
+ sox_loop_sustain_decay = 64 /**< AIFF style, one sustain & one decay loop = 64 */
};
-/* Boolean type, assignment (but not necessarily binary) compatible with C++ bool */
-typedef enum sox_bool {- sox_false,
- sox_true
-} sox_bool;
+/**
+Plugins API:
+Is file a real file, a pipe, or a url?
+*/
+typedef enum lsx_io_type
+{+ lsx_io_file, /**< File is a real file = 0. */
+ lsx_io_pipe, /**< File is a pipe (no seeking) = 1. */
+ lsx_io_url /**< File is a URL (no seeking) = 2. */
+} lsx_io_type;
-#define SOX_INT_MIN(bits) (1 <<((bits)-1)) /* i.e. 0x80, 0x8000, 0x80000000 */
-#define SOX_INT_MAX(bits) (((unsigned)-1)>>(33-(bits))) /* i.e. 0x7F, 0x7FFF, 0x7FFFFFFF */
-#define SOX_UINT_MAX(bits) (SOX_INT_MIN(bits)|SOX_INT_MAX(bits)) /* i.e. 0xFF, 0xFFFF, 0xFFFFFFFF */
+/*****************************************************************************
+Macros:
+*****************************************************************************/
-#define SOX_INT8_MAX SOX_INT_MAX(8) /* = 0x7F */
-#define SOX_INT16_MAX SOX_INT_MAX(16) /* = 0x7FFF */
-#define SOX_INT24_MAX SOX_INT_MAX(24) /* = 0x007FFFFF */
-#define SOX_INT32_MAX SOX_INT_MAX(32) /* = 0x7FFFFFFF */
+/**
+Client API:
+Compute a 32-bit integer API version from three 8-bit parts.
+@param a Major version.
+@param b Minor version.
+@param c Revision or build number.
+@returns 32-bit integer API version 0x000a0b0c.
+*/
+#define SOX_LIB_VERSION(a,b,c) (((a) << 16) + ((b) << 8) + (c))
-/* native SoX audio sample type */
-typedef sox_int32_t sox_sample_t;
+/**
+Client API:
+The API version of the sox.h file. It is not meant to follow the version
+number of SoX but it has historically. Please do not count on
+SOX_LIB_VERSION_CODE staying in sync with the libSoX version.
+*/
+#define SOX_LIB_VERSION_CODE SOX_LIB_VERSION(14, 4, 0)
-/* Minimum and maximum values a sample can hold. */
-#define SOX_SAMPLE_PRECISION 32 /* bits in a sox_sample_t = 32 */
-#define SOX_SAMPLE_MAX (sox_sample_t)SOX_INT_MAX(32) /* max value for sox_sample_t = 0x7FFFFFFF */
-#define SOX_SAMPLE_MIN (sox_sample_t)SOX_INT_MIN(32) /* min value for sox_sample_t = 0x80000000 */
+/**
+Client API:
+Returns the smallest (negative) value storable in a twos-complement signed
+integer with the specified number of bits, cast to an unsigned integer;
+for example, SOX_INT_MIN(8) = 0x80, SOX_INT_MIN(16) = 0x8000, etc.
+@param bits Size of value for which to calculate minimum.
+@returns the smallest (negative) value storable in a twos-complement signed
+integer with the specified number of bits, cast to an unsigned integer.
+*/
+#define SOX_INT_MIN(bits) (1 <<((bits)-1))
+/**
+Client API:
+Returns the largest (positive) value storable in a twos-complement signed
+integer with the specified number of bits, cast to an unsigned integer;
+for example, SOX_INT_MAX(8) = 0x7F, SOX_INT_MAX(16) = 0x7FFF, etc.
+@param bits Size of value for which to calculate maximum.
+@returns the largest (positive) value storable in a twos-complement signed
+integer with the specified number of bits, cast to an unsigned integer.
+*/
+#define SOX_INT_MAX(bits) (((unsigned)-1)>>(33-(bits)))
+/**
+Client API:
+Returns the largest value storable in an unsigned integer with the specified
+number of bits; for example, SOX_UINT_MAX(8) = 0xFF,
+SOX_UINT_MAX(16) = 0xFFFF, etc.
+@param bits Size of value for which to calculate maximum.
+@returns the largest value storable in an unsigned integer with the specified
+number of bits.
+*/
+#define SOX_UINT_MAX(bits) (SOX_INT_MIN(bits)|SOX_INT_MAX(bits))
+
+/**
+Client API:
+Returns 0x7F.
+*/
+#define SOX_INT8_MAX SOX_INT_MAX(8)
+
+/**
+Client API:
+Returns 0x7FFF.
+*/
+#define SOX_INT16_MAX SOX_INT_MAX(16)
+
+/**
+Client API:
+Returns 0x7FFFFF.
+*/
+#define SOX_INT24_MAX SOX_INT_MAX(24)
+
+/**
+Client API:
+Returns 0x7FFFFFFF.
+*/
+#define SOX_INT32_MAX SOX_INT_MAX(32)
+
+/**
+Client API:
+Bits in a sox_sample_t = 32.
+*/
+#define SOX_SAMPLE_PRECISION 32
+
+/**
+Client API:
+Max value for sox_sample_t = 0x7FFFFFFF.
+*/
+#define SOX_SAMPLE_MAX (sox_sample_t)SOX_INT_MAX(32)
+
+/**
+Client API:
+Min value for sox_sample_t = 0x80000000.
+*/
+#define SOX_SAMPLE_MIN (sox_sample_t)SOX_INT_MIN(32)
+
+
/* Conversions: Linear PCM <--> sox_sample_t
*
* I/O Input sox_sample_t Clips? Input sox_sample_t Clips?
@@ -442,42 +762,237 @@
* the upper-most bit then treating them as signed integers.
*/
+/**
+Client API:
+Declares the temporary local variables that are required when using SOX
+conversion macros.
+*/
#define SOX_SAMPLE_LOCALS sox_sample_t sox_macro_temp_sample LSX_UNUSED; \
double sox_macro_temp_double LSX_UNUSED
-#define SOX_SAMPLE_NEG SOX_INT_MIN(32) /* sign bit for sox_sample_t = 0x80000000 */
+/**
+Client API:
+Sign bit for sox_sample_t = 0x80000000.
+*/
+#define SOX_SAMPLE_NEG SOX_INT_MIN(32)
+
+/**
+Client API:
+Converts sox_sample_t to an unsigned integer of width (bits).
+@param bits Width of resulting sample (1 through 32).
+@param d Input sample to be converted.
+@param clips Variable that is incremented if the result is too big.
+@returns Unsigned integer of width (bits).
+*/
#define SOX_SAMPLE_TO_UNSIGNED(bits,d,clips) \
(sox_uint##bits##_t)(SOX_SAMPLE_TO_SIGNED(bits,d,clips)^SOX_INT_MIN(bits))
+
+/**
+Client API:
+Converts sox_sample_t to a signed integer of width (bits).
+@param bits Width of resulting sample (1 through 32).
+@param d Input sample to be converted.
+@param clips Variable that is incremented if the result is too big.
+@returns Signed integer of width (bits).
+*/
#define SOX_SAMPLE_TO_SIGNED(bits,d,clips) \
(sox_int##bits##_t)(LSX_USE_VAR(sox_macro_temp_double),sox_macro_temp_sample=(d),sox_macro_temp_sample>SOX_SAMPLE_MAX-(1<<(31-bits))?++(clips),SOX_INT_MAX(bits):((sox_uint32_t)(sox_macro_temp_sample+(1<<(31-bits))))>>(32-bits))
+
+/**
+Client API:
+Converts signed integer of width (bits) to sox_sample_t.
+@param bits Width of input sample (1 through 32).
+@param d Input sample to be converted.
+@returns SoX native sample value.
+*/
#define SOX_SIGNED_TO_SAMPLE(bits,d)((sox_sample_t)(d)<<(32-bits))
+
+/**
+Client API:
+Converts unsigned integer of width (bits) to sox_sample_t.
+@param bits Width of input sample (1 through 32).
+@param d Input sample to be converted.
+@returns SoX native sample value.
+*/
#define SOX_UNSIGNED_TO_SAMPLE(bits,d)(SOX_SIGNED_TO_SAMPLE(bits,d)^SOX_SAMPLE_NEG)
+/**
+Client API:
+Converts unsigned 8-bit integer to sox_sample_t.
+@param d Input sample to be converted.
+@param clips The parameter is not used.
+@returns SoX native sample value.
+*/
#define SOX_UNSIGNED_8BIT_TO_SAMPLE(d,clips) SOX_UNSIGNED_TO_SAMPLE(8,d)
+
+/**
+Client API:
+Converts signed 8-bit integer to sox_sample_t.
+@param d Input sample to be converted.
+@param clips The parameter is not used.
+@returns SoX native sample value.
+*/
#define SOX_SIGNED_8BIT_TO_SAMPLE(d,clips) SOX_SIGNED_TO_SAMPLE(8,d)
+
+/**
+Client API:
+Converts unsigned 16-bit integer to sox_sample_t.
+@param d Input sample to be converted.
+@param clips The parameter is not used.
+@returns SoX native sample value.
+*/
#define SOX_UNSIGNED_16BIT_TO_SAMPLE(d,clips) SOX_UNSIGNED_TO_SAMPLE(16,d)
+
+/**
+Client API:
+Converts signed 16-bit integer to sox_sample_t.
+@param d Input sample to be converted.
+@param clips The parameter is not used.
+@returns SoX native sample value.
+*/
#define SOX_SIGNED_16BIT_TO_SAMPLE(d,clips) SOX_SIGNED_TO_SAMPLE(16,d)
+
+/**
+Client API:
+Converts unsigned 24-bit integer to sox_sample_t.
+@param d Input sample to be converted.
+@param clips The parameter is not used.
+@returns SoX native sample value.
+*/
#define SOX_UNSIGNED_24BIT_TO_SAMPLE(d,clips) SOX_UNSIGNED_TO_SAMPLE(24,d)
+
+/**
+Client API:
+Converts signed 24-bit integer to sox_sample_t.
+@param d Input sample to be converted.
+@param clips The parameter is not used.
+@returns SoX native sample value.
+*/
#define SOX_SIGNED_24BIT_TO_SAMPLE(d,clips) SOX_SIGNED_TO_SAMPLE(24,d)
+
+/**
+Client API:
+Converts unsigned 32-bit integer to sox_sample_t.
+@param d Input sample to be converted.
+@param clips The parameter is not used.
+@returns SoX native sample value.
+*/
#define SOX_UNSIGNED_32BIT_TO_SAMPLE(d,clips) ((sox_sample_t)(d)^SOX_SAMPLE_NEG)
+
+/**
+Client API:
+Converts signed 32-bit integer to sox_sample_t.
+@param d Input sample to be converted.
+@param clips The parameter is not used.
+@returns SoX native sample value.
+*/
#define SOX_SIGNED_32BIT_TO_SAMPLE(d,clips) (sox_sample_t)(d)
+
+/**
+Client API:
+Converts 32-bit float to sox_sample_t.
+@param d Input sample to be converted, range [-1, 1).
+@param clips Variable to increment if the input sample is too large or too small.
+@returns SoX native sample value.
+*/
#define SOX_FLOAT_32BIT_TO_SAMPLE(d,clips) (sox_sample_t)(LSX_USE_VAR(sox_macro_temp_sample),sox_macro_temp_double=(d)*(SOX_SAMPLE_MAX+1.),sox_macro_temp_double<SOX_SAMPLE_MIN?++(clips),SOX_SAMPLE_MIN:sox_macro_temp_double>=SOX_SAMPLE_MAX+1.?sox_macro_temp_double>SOX_SAMPLE_MAX+1.?++(clips),SOX_SAMPLE_MAX:SOX_SAMPLE_MAX:sox_macro_temp_double)
+
+/**
+Client API:
+Converts 64-bit float to sox_sample_t.
+@param d Input sample to be converted, range [-1, 1).
+@param clips Variable to increment if the input sample is too large or too small.
+@returns SoX native sample value.
+*/
#define SOX_FLOAT_64BIT_TO_SAMPLE(d,clips) (sox_sample_t)(LSX_USE_VAR(sox_macro_temp_sample),sox_macro_temp_double=(d)*(SOX_SAMPLE_MAX+1.),sox_macro_temp_double<0?sox_macro_temp_double<=SOX_SAMPLE_MIN-.5?++(clips),SOX_SAMPLE_MIN:sox_macro_temp_double-.5:sox_macro_temp_double>=SOX_SAMPLE_MAX+.5?sox_macro_temp_double>SOX_SAMPLE_MAX+1.?++(clips),SOX_SAMPLE_MAX:SOX_SAMPLE_MAX:sox_macro_temp_double+.5)
+
+/**
+Client API:
+Converts SoX native sample to an unsigned 8-bit integer.
+@param d Input sample to be converted.
+@param clips Variable to increment if input sample is too large.
+*/
#define SOX_SAMPLE_TO_UNSIGNED_8BIT(d,clips) SOX_SAMPLE_TO_UNSIGNED(8,d,clips)
+
+/**
+Client API:
+Converts SoX native sample to an signed 8-bit integer.
+@param d Input sample to be converted.
+@param clips Variable to increment if input sample is too large.
+*/
#define SOX_SAMPLE_TO_SIGNED_8BIT(d,clips) SOX_SAMPLE_TO_SIGNED(8,d,clips)
+
+/**
+Client API:
+Converts SoX native sample to an unsigned 16-bit integer.
+@param d Input sample to be converted.
+@param clips Variable to increment if input sample is too large.
+*/
#define SOX_SAMPLE_TO_UNSIGNED_16BIT(d,clips) SOX_SAMPLE_TO_UNSIGNED(16,d,clips)
+
+/**
+Client API:
+Converts SoX native sample to a signed 16-bit integer.
+@param d Input sample to be converted.
+@param clips Variable to increment if input sample is too large.
+*/
#define SOX_SAMPLE_TO_SIGNED_16BIT(d,clips) SOX_SAMPLE_TO_SIGNED(16,d,clips)
+
+/**
+Client API:
+Converts SoX native sample to an unsigned 24-bit integer.
+@param d Input sample to be converted.
+@param clips Variable to increment if input sample is too large.
+*/
#define SOX_SAMPLE_TO_UNSIGNED_24BIT(d,clips) SOX_SAMPLE_TO_UNSIGNED(24,d,clips)
+
+/**
+Client API:
+Converts SoX native sample to a signed 24-bit integer.
+@param d Input sample to be converted.
+@param clips Variable to increment if input sample is too large.
+*/
#define SOX_SAMPLE_TO_SIGNED_24BIT(d,clips) SOX_SAMPLE_TO_SIGNED(24,d,clips)
+
+/**
+Client API:
+Converts SoX native sample to an unsigned 32-bit integer.
+@param d Input sample to be converted.
+@param clips The parameter is not used.
+*/
#define SOX_SAMPLE_TO_UNSIGNED_32BIT(d,clips) (sox_uint32_t)((d)^SOX_SAMPLE_NEG)
+
+/**
+Client API:
+Converts SoX native sample to a signed 32-bit integer.
+@param d Input sample to be converted.
+@param clips The parameter is not used.
+*/
#define SOX_SAMPLE_TO_SIGNED_32BIT(d,clips) (sox_int32_t)(d)
+
+/**
+Client API:
+Converts SoX native sample to a 32-bit float.
+@param d Input sample to be converted.
+@param clips Variable to increment if input sample is too large.
+*/
#define SOX_SAMPLE_TO_FLOAT_32BIT(d,clips) (LSX_USE_VAR(sox_macro_temp_double),sox_macro_temp_sample=(d),sox_macro_temp_sample>SOX_SAMPLE_MAX-128?++(clips),1:(((sox_macro_temp_sample+128)&~255)*(1./(SOX_SAMPLE_MAX+1.))))
+
+/**
+Client API:
+Converts SoX native sample to a 64-bit float.
+@param d Input sample to be converted.
+@param clips The parameter is not used.
+*/
#define SOX_SAMPLE_TO_FLOAT_64BIT(d,clips) ((d)*(1./(SOX_SAMPLE_MAX+1.)))
-
-/* MACRO to clip a data type that is greater then sox_sample_t to
- * sox_sample_t's limits and increment a counter if clipping occurs.
- */
+/**
+Client API:
+Clips a value of a type that is larger then sox_sample_t (for example, int64)
+to sox_sample_t's limits and increment a counter if clipping occurs.
+@param samp Value (lvalue) to be clipped, updated as necessary.
+@param clips Value (lvalue) that is incremented if clipping is needed.
+*/
#define SOX_SAMPLE_CLIP_COUNT(samp, clips) \
do { \if (samp > SOX_SAMPLE_MAX) \
@@ -486,908 +1001,1625 @@
{ samp = SOX_SAMPLE_MIN; clips++; } \} while (0)
-/* Rvalue MACRO to round and clip a double to a sox_sample_t,
- * and increment a counter if clipping occurs.
- */
+/**
+Client API:
+Clips a value of a type that is larger then sox_sample_t (for example, int64)
+to sox_sample_t's limits and increment a counter if clipping occurs.
+@param d Value (rvalue) to be clipped.
+@param clips Value (lvalue) that is incremented if clipping is needed.
+@returns Clipped value.
+*/
#define SOX_ROUND_CLIP_COUNT(d, clips) \
((d) < 0? (d) <= SOX_SAMPLE_MIN - 0.5? ++(clips), SOX_SAMPLE_MIN: (d) - 0.5 \
: (d) >= SOX_SAMPLE_MAX + 0.5? ++(clips), SOX_SAMPLE_MAX: (d) + 0.5)
-/* Rvalue MACRO to clip an integer to a given number of bits
- * and increment a counter if clipping occurs.
- */
+/**
+Client API:
+Clips a value to the limits of a signed integer of the specified width
+and increment a counter if clipping occurs.
+@param bits Width (in bits) of target integer type.
+@param i Value (rvalue) to be clipped.
+@param clips Value (lvalue) that is incremented if clipping is needed.
+@returns Clipped value.
+*/
#define SOX_INTEGER_CLIP_COUNT(bits,i,clips) ( \
(i) >(1 << ((bits)-1))- 1? ++(clips),(1 << ((bits)-1))- 1 : \
(i) <-1 << ((bits)-1) ? ++(clips),-1 << ((bits)-1) : (i))
+
+/**
+Client API:
+Clips a value to the limits of a 16-bit signed integer and increment a counter
+if clipping occurs.
+@param i Value (rvalue) to be clipped.
+@param clips Value (lvalue) that is incremented if clipping is needed.
+@returns Clipped value.
+*/
#define SOX_16BIT_CLIP_COUNT(i,clips) SOX_INTEGER_CLIP_COUNT(16,i,clips)
+
+/**
+Client API:
+Clips a value to the limits of a 24-bit signed integer and increment a counter
+if clipping occurs.
+@param i Value (rvalue) to be clipped.
+@param clips Value (lvalue) that is incremented if clipping is needed.
+@returns Clipped value.
+*/
#define SOX_24BIT_CLIP_COUNT(i,clips) SOX_INTEGER_CLIP_COUNT(24,i,clips)
+#define SOX_SIZE_MAX ((size_t)(-1)) /**< Client API: Maximum value of size_t. */
-#define SOX_SIZE_MAX ((size_t)(-1)) /* maximum value of size_t */
+#define SOX_UNSPEC 0 /**< Client API: Members of sox_signalinfo_t are set to SOX_UNSPEC (= 0) if the actual value is not yet known. */
+#define SOX_IGNORE_LENGTH (sox_uint64_t)(-1) /**< Client API: sox_signalinfo_t.length is set to SOX_IGNORE_LENGTH (= -1) if the actual length is not yet known. */
-/* function-pointer type of globals.output_message_handler */
-typedef void (SOX_API * sox_output_message_handler_t)(
- unsigned level, /* 1 = FAIL, 2 = WARN, 3 = INFO, 4 = DEBUG, 5 = DEBUG_MORE, 6 = DEBUG_MOST. */
- LSX_PARAM_IN_Z const char *filename, /* Source code __FILENAME__ from which message originates. */
- LSX_PARAM_IN_PRINTF const char *fmt, /* Message format string. */
- LSX_PARAM_IN va_list ap); /* Message format parameters. */
+#define SOX_DEFAULT_CHANNELS 2 /**< Client API: Default channel count is 2 (stereo). */
+#define SOX_DEFAULT_RATE 48000 /**< Client API: Default rate is 48000Hz. */
+#define SOX_DEFAULT_PRECISION 16 /**< Client API: Default precision is 16 bits per sample. */
+#define SOX_DEFAULT_ENCODING SOX_ENCODING_SIGN2 /**< Client API: Default encoding is SIGN2 (linear 2's complement PCM). */
-/* Global parameters (for effects & formats) */
-typedef struct sox_globals_t {-/* public: */
- unsigned verbosity; /* messages are only written if globals.verbosity >= message.level */
- sox_output_message_handler_t output_message_handler; /* client-specified message output callback */
- sox_bool repeatable; /* true to use pre-determined timestamps and PRNG seed */
+#define SOX_LOOP_NONE ((unsigned char)sox_loop_none) /**< Client API: single-shot = 0 */
+#define SOX_LOOP_8 ((unsigned char)sox_loop_8) /**< Client API: 8 loops = 32 */
+#define SOX_LOOP_SUSTAIN_DECAY ((unsigned char)sox_loop_sustain_decay) /**< Client API: AIFF style, one sustain & one decay loop = 64 */
-/* The following is used at times in libSoX when alloc()ing buffers
- * to perform file I/O. It can be useful to pass in similar sized
- * data to get max performance. */
- size_t bufsiz; /* default size (in bytes) used for blocks of sample data */
- size_t input_bufsiz; /* default size (in bytes) used for blocks of input sample data */
+#define SOX_MAX_NLOOPS 8 /**< Client API: Maximum number of loops supported by sox_oob_t = 8. */
- sox_int32_t ranqd1; /* Can be used to re-seed libSoX's PRNG */
+#define SOX_FILE_NOSTDIO 0x0001 /**< Client API: Does not use stdio routines */
+#define SOX_FILE_DEVICE 0x0002 /**< Client API: File is an audio device */
+#define SOX_FILE_PHONY 0x0004 /**< Client API: Phony file/device (for example /dev/null) */
+#define SOX_FILE_REWIND 0x0008 /**< Client API: File should be rewound to write header */
+#define SOX_FILE_BIT_REV 0x0010 /**< Client API: Is file bit-reversed? */
+#define SOX_FILE_NIB_REV 0x0020 /**< Client API: Is file nibble-reversed? */
+#define SOX_FILE_ENDIAN 0x0040 /**< Client API: Is file format endian? */
+#define SOX_FILE_ENDBIG 0x0080 /**< Client API: For endian file format, is it big endian? */
+#define SOX_FILE_MONO 0x0100 /**< Client API: Do channel restrictions allow mono? */
+#define SOX_FILE_STEREO 0x0200 /**< Client API: Do channel restrictions allow stereo? */
+#define SOX_FILE_QUAD 0x0400 /**< Client API: Do channel restrictions allow quad? */
-/* private: */
- char const * stdin_in_use_by; /* tracks the name of the handler currently using stdin */
- char const * stdout_in_use_by; /* tracks the name of the handler currently using stdout */
- char const * subsystem; /* tracks the name of the handler currently writing an output message */
- char * tmp_path; /* client-configured path to use for temporary files */
- sox_bool use_magic; /* true if client has requested use of 'magic' file-type detection */
- sox_bool use_threads; /* true if client has requested parallel effects processing */
-} sox_globals_t;
+#define SOX_FILE_CHANS (SOX_FILE_MONO | SOX_FILE_STEREO | SOX_FILE_QUAD) /**< Client API: No channel restrictions */
+#define SOX_FILE_LIT_END (SOX_FILE_ENDIAN | 0) /**< Client API: File is little-endian */
+#define SOX_FILE_BIG_END (SOX_FILE_ENDIAN | SOX_FILE_ENDBIG) /**< Client API: File is big-endian */
-/* Returns the SoX global settings. */
-LSX_RETURN_VALID LSX_RETURN_PURE sox_globals_t *
-SOX_API sox_get_globals(void);
+#define SOX_EFF_CHAN 1 /**< Client API: Effect might alter the number of channels */
+#define SOX_EFF_RATE 2 /**< Client API: Effect might alter sample rate */
+#define SOX_EFF_PREC 4 /**< Client API: Effect might alter sample precision */
+#define SOX_EFF_LENGTH 8 /**< Client API: Effect might alter audio length */
+#define SOX_EFF_MCHAN 16 /**< Client API: Effect handles multiple channels internally */
+#define SOX_EFF_NULL 32 /**< Client API: Effect does nothing (can be optimized out of flow) */
+#define SOX_EFF_DEPRECATED 64 /**< Client API: Effect will soon be removed from SoX */
+#define SOX_EFF_GAIN 128 /**< Client API: Effect does not support gain -r */
+#define SOX_EFF_MODIFY 256 /**< Client API: Effect does not modify samples (just watches as data goes through) */
+#define SOX_EFF_ALPHA 512 /**< Client API: Effect is experimental/incomplete */
+#define SOX_EFF_INTERNAL 1024 /**< Client API: Effect present libSoX but not valid for use by SoX command-line tools */
-#define sox_globals (*sox_get_globals())
+/**
+Client API:
+When used as the "whence" parameter of sox_seek, indicates that the specified
+offset is relative to the beginning of the file.
+*/
+#define SOX_SEEK_SET 0
-/* samples per second = double */
-typedef double sox_rate_t;
+/*****************************************************************************
+Forward declarations:
+*****************************************************************************/
-#define SOX_UNSPEC 0 /* unknown value for signal parameter = 0 */
-#define SOX_IGNORE_LENGTH (sox_uint64_t)(-1) /* unspecified length for signal.length = -1 */
+typedef struct sox_format_t sox_format_t;
+typedef struct sox_effect_t sox_effect_t;
+typedef struct sox_effect_handler_t sox_effect_handler_t;
+typedef struct sox_format_handler_t sox_format_handler_t;
-/* Signal parameters; SOX_UNSPEC (= 0) if unknown */
-typedef struct sox_signalinfo_t {- sox_rate_t rate; /* samples per second, 0 if unknown */
- unsigned channels; /* number of sound channels, 0 if unknown */
- unsigned precision; /* bits per sample, 0 if unknown */
- sox_uint64_t length; /* samples * chans in file, 0 if unknown, -1 if unspecified */
- double * mult; /* Effects headroom multiplier; may be null */
-} sox_signalinfo_t;
+/*****************************************************************************
+Function pointers:
+*****************************************************************************/
-/* Format of sample data */
-typedef enum sox_encoding_t {- SOX_ENCODING_UNKNOWN , /* encoding has not yet been determined */
+/**
+Client API:
+Callback to write a message to an output device (console or log file),
+used by sox_globals_t.output_message_handler.
+*/
+typedef void (LSX_API * sox_output_message_handler_t)(
+ unsigned level, /* 1 = FAIL, 2 = WARN, 3 = INFO, 4 = DEBUG, 5 = DEBUG_MORE, 6 = DEBUG_MOST. */
+ LSX_PARAM_IN_Z char const * filename, /* Source code __FILENAME__ from which message originates. */
+ LSX_PARAM_IN_PRINTF char const * fmt, /* Message format string. */
+ LSX_PARAM_IN va_list ap /* Message format parameters. */
+ );
- SOX_ENCODING_SIGN2 , /* signed linear 2's comp: Mac */
- SOX_ENCODING_UNSIGNED , /* unsigned linear: Sound Blaster */
- SOX_ENCODING_FLOAT , /* floating point (binary format) */
- SOX_ENCODING_FLOAT_TEXT, /* floating point (text format) */
- SOX_ENCODING_FLAC , /* FLAC compression */
- SOX_ENCODING_HCOM , /* Mac FSSD files with Huffman compression */
- SOX_ENCODING_WAVPACK , /* WavPack with integer samples */
- SOX_ENCODING_WAVPACKF , /* WavPack with float samples */
- SOX_ENCODING_ULAW , /* u-law signed logs: US telephony, SPARC */
- SOX_ENCODING_ALAW , /* A-law signed logs: non-US telephony, Psion */
- SOX_ENCODING_G721 , /* G.721 4-bit ADPCM */
- SOX_ENCODING_G723 , /* G.723 3 or 5 bit ADPCM */
- SOX_ENCODING_CL_ADPCM , /* Creative Labs 8 --> 2,3,4 bit Compressed PCM */
- SOX_ENCODING_CL_ADPCM16, /* Creative Labs 16 --> 4 bit Compressed PCM */
- SOX_ENCODING_MS_ADPCM , /* Microsoft Compressed PCM */
- SOX_ENCODING_IMA_ADPCM , /* IMA Compressed PCM */
- SOX_ENCODING_OKI_ADPCM , /* Dialogic/OKI Compressed PCM */
- SOX_ENCODING_DPCM , /* Differential PCM: Fasttracker 2 (xi) */
- SOX_ENCODING_DWVW , /* Delta Width Variable Word */
- SOX_ENCODING_DWVWN , /* Delta Width Variable Word N-bit */
- SOX_ENCODING_GSM , /* GSM 6.10 33byte frame lossy compression */
- SOX_ENCODING_MP3 , /* MP3 compression */
- SOX_ENCODING_VORBIS , /* Vorbis compression */
- SOX_ENCODING_AMR_WB , /* AMR-WB compression */
- SOX_ENCODING_AMR_NB , /* AMR-NB compression */
- SOX_ENCODING_CVSD , /* Continuously Variable Slope Delta modulation */
- SOX_ENCODING_LPC10 , /* Linear Predictive Coding */
+/**
+Client API:
+Callback to retrieve information about a format handler,
+used by sox_format_tab_t.fn.
+@returns format handler information.
+*/
+typedef sox_format_handler_t const * (LSX_API * sox_format_fn_t)(void);
- SOX_ENCODINGS /* End of list marker */
-} sox_encoding_t;
+/**
+Client API:
+Callback to get information about an effect handler,
+used by the table returned from sox_get_effect_fns(void).
+@returns Pointer to information about an effect handler.
+*/
+typedef sox_effect_handler_t const * (LSX_API *sox_effect_fn_t)(void);
-/* Flags for sox_encodings_info_t: lossless/lossy1/lossy2 */
-typedef enum sox_encodings_flags_t {- sox_encodings_none = 0, /* no flags specified (implies lossless encoding) */
- sox_encodings_lossy1 = 1, /* encode, decode: lossy once */
- sox_encodings_lossy2 = 2 /* encode, decode, encode, decode: lossy twice */
-} sox_encodings_flags_t;
+/**
+Client API:
+Callback to initialize reader (decoder), used by
+sox_format_handler.startread.
+@returns SOX_SUCCESS if successful.
+*/
+typedef int (LSX_API * sox_format_handler_startread)(
+ LSX_PARAM_INOUT sox_format_t * ft /**< Format pointer. */
+ );
-#define SOX_LOSSY1 sox_encodings_lossy1 /* encode, decode: lossy once */
-#define SOX_LOSSY2 sox_encodings_lossy2 /* encode, decode, encode, decode: lossy twice */
+/**
+Client API:
+Callback to read (decode) a block of samples,
+used by sox_format_handler.read.
+@returns number of samples read, or 0 if unsuccessful.
+*/
+typedef size_t (LSX_API * sox_format_handler_read)(
+ LSX_PARAM_INOUT sox_format_t * ft, /**< Format pointer. */
+ LSX_PARAM_OUT_CAP_POST_COUNT(len,return) sox_sample_t *buf, /**< Buffer from which to read samples. */
+ size_t len /**< Number of samples available in buf. */
+ );
-typedef struct sox_encodings_info_t {- sox_encodings_flags_t flags; /* lossy once (lossy1), lossy twice (lossy2), or lossless (0) */
- char const * name; /* encoding name */
- char const * desc; /* encoding description */
-} sox_encodings_info_t;
+/**
+Client API:
+Callback to close reader (decoder),
+used by sox_format_handler.stopread.
+@returns SOX_SUCCESS if successful.
+*/
+typedef int (LSX_API * sox_format_handler_stopread)(
+ LSX_PARAM_INOUT sox_format_t * ft /**< Format pointer. */
+ );
-/* Returns the list of available encodings. End of list indicated by name == NULL. */
-LSX_RETURN_ARRAY LSX_RETURN_PURE sox_encodings_info_t const *
-SOX_API sox_get_encodings_info(void);
+/**
+Client API:
+Callback to initialize writer (encoder),
+used by sox_format_handler.startwrite.
+@returns SOX_SUCCESS if successful.
+*/
+typedef int (LSX_API * sox_format_handler_startwrite)(
+ LSX_PARAM_INOUT sox_format_t * ft /**< Format pointer. */
+ );
-#define sox_encodings_info (sox_get_encodings_info())
+/**
+Client API:
+Callback to write (encode) a block of samples,
+used by sox_format_handler.write.
+@returns number of samples written, or 0 if unsuccessful.
+*/
+typedef size_t (LSX_API * sox_format_handler_write)(
+ LSX_PARAM_INOUT sox_format_t * ft, /**< Format pointer. */
+ LSX_PARAM_IN_COUNT(len) sox_sample_t const * buf, /**< Buffer to which samples are written. */
+ size_t len /**< Capacity of buf, measured in samples. */
+ );
-/* yes, no, or default (auto-detect) */
-typedef enum sox_option_t {- SOX_OPTION_NO,
- SOX_OPTION_YES,
- SOX_OPTION_DEFAULT
-} sox_option_t;
+/**
+Client API:
+Callback to close writer (decoder),
+used by sox_format_handler.stopwrite.
+@returns SOX_SUCCESS if successful.
+*/
+typedef int (LSX_API * sox_format_handler_stopwrite)(
+ LSX_PARAM_INOUT sox_format_t * ft /**< Format pointer. */
+ );
-/* Encoding parameters */
-typedef struct sox_encodinginfo_t {- sox_encoding_t encoding; /* format of sample numbers */
- unsigned bits_per_sample;/* 0 if unknown or variable; uncompressed value if lossless; compressed value if lossy */
- double compression; /* compression factor (where applicable) */
+/**
+Client API:
+Callback to reposition reader,
+used by sox_format_handler.seek.
+@returns SOX_SUCCESS if successful.
+*/
+typedef int (LSX_API * sox_format_handler_seek)(
+ LSX_PARAM_INOUT sox_format_t * ft, /**< Format pointer. */
+ sox_uint64_t offset /**< Sample offset to which reader should be positioned. */
+ );
- /* If these 3 variables are set to SOX_OPTION_DEFAULT, then, during
- * sox_open_read or sox_open_write, libSoX will set them to either
- * NO or YES according to the machine or format default. */
- sox_option_t reverse_bytes; /* endiannesses... */
- sox_option_t reverse_nibbles;
- sox_option_t reverse_bits;
+/**
+Client API:
+Callback to parse command-line arguments (called once per effect),
+used by sox_effect_handler.getopts.
+@returns SOX_SUCCESS if successful.
+*/
+typedef int (LSX_API * sox_effect_handler_getopts)(
+ LSX_PARAM_INOUT sox_effect_t * effp, /**< Effect pointer. */
+ int argc, /**< Number of arguments in argv. */
+ LSX_PARAM_IN_COUNT(argc) char *argv[] /**< Array of command-line arguments. */
+ );
- sox_bool opposite_endian;
-} sox_encodinginfo_t;
+/**
+Client API:
+Callback to initialize effect (called once per flow),
+used by sox_effect_handler.start.
+@returns SOX_SUCCESS if successful.
+*/
+typedef int (LSX_API * sox_effect_handler_start)(
+ LSX_PARAM_INOUT sox_effect_t * effp /**< Effect pointer. */
+ );
-/* fills in an encodinginfo with default values */
-void
-SOX_API sox_init_encodinginfo(
- LSX_PARAM_OUT sox_encodinginfo_t * e);
+/**
+Client API:
+Callback to process samples,
+used by sox_effect_handler.flow.
+@returns SOX_SUCCESS if successful.
+*/
+typedef int (LSX_API * sox_effect_handler_flow)(
+ LSX_PARAM_INOUT sox_effect_t * effp, /**< Effect pointer. */
+ LSX_PARAM_IN_COUNT(*isamp) sox_sample_t const * ibuf, /**< Buffer from which to read samples. */
+ LSX_PARAM_OUT_CAP_POST_COUNT(*osamp,*osamp) sox_sample_t * obuf, /**< Buffer to which samples are written. */
+ LSX_PARAM_INOUT size_t *isamp, /**< On entry, contains capacity of ibuf; on exit, contains number of samples consumed. */
+ LSX_PARAM_INOUT size_t *osamp /**< On entry, contains capacity of obuf; on exit, contains number of samples written. */
+ );
-/* Given an encoding (i.e. SIGN2) and the encoded bits_per_sample (i.e. 16),
- * returns the number of useful bits per sample in the decoded data (i.e. 16).
- * Returns 0 to indicate that the value returned by the format handler should
- * be used instead of a pre-determined precision. */
-LSX_RETURN_PURE unsigned /* Returns the number of useful decoded bits per sample */
-SOX_API sox_precision(
- sox_encoding_t encoding, /* Encoded format */
- unsigned bits_per_sample); /* Encoded bits per sample */
+/**
+Client API:
+Callback to finish getting output after input is complete,
+used by sox_effect_handler.drain.
+@returns SOX_SUCCESS if successful.
+*/
+typedef int (LSX_API * sox_effect_handler_drain)(
+ LSX_PARAM_INOUT sox_effect_t * effp, /**< Effect pointer. */
+ LSX_PARAM_OUT_CAP_POST_COUNT(*osamp,*osamp) sox_sample_t *obuf, /**< Buffer to which samples are written. */
+ LSX_PARAM_INOUT size_t *osamp /**< On entry, contains capacity of obuf; on exit, contains number of samples written. */
+ );
-/* Defaults for common hardware */
-#define SOX_DEFAULT_CHANNELS 2 /* = 2 (stereo) */
-#define SOX_DEFAULT_RATE 48000 /* = 48000Hz */
-#define SOX_DEFAULT_PRECISION 16 /* = 16 bits per sample */
-#define SOX_DEFAULT_ENCODING SOX_ENCODING_SIGN2 /* = SIGN2 (linear 2's complement PCM) */
+/**
+Client API:
+Callback to shut down effect (called once per flow),
+used by sox_effect_handler.stop.
+@returns SOX_SUCCESS if successful.
+*/
+typedef int (LSX_API * sox_effect_handler_stop)(
+ LSX_PARAM_INOUT sox_effect_t * effp /**< Effect pointer. */
+ );
-/* Loop parameters */
+/**
+Client API:
+Callback to shut down effect (called once per effect),
+used by sox_effect_handler.kill.
+@returns SOX_SUCCESS if successful.
+*/
+typedef int (LSX_API * sox_effect_handler_kill)(
+ LSX_PARAM_INOUT sox_effect_t * effp /**< Effect pointer. */
+ );
-/* Loop modes, upper 4 bits mask the loop blass, lower 4 bits describe */
-/* the loop behaviour, ie. single shot, bidirectional etc. */
-enum sox_loop_flags_t {- sox_loop_none = 0, /* single-shot = 0 */
- sox_loop_forward = 1, /* forward loop = 1 */
- sox_loop_forward_back = 2, /* forward/back loop = 2 */
- sox_loop_8 = 32, /* 8 loops (??) = 32 */
- sox_loop_sustain_decay = 64 /* AIFF style, one sustain & one decay loop = 64 */
-};
-#define SOX_LOOP_NONE ((unsigned char)sox_loop_none) /* single-shot = 0 */
-#define SOX_LOOP_8 ((unsigned char)sox_loop_8) /* 8 loops (??) = 32 */
-#define SOX_LOOP_SUSTAIN_DECAY ((unsigned char)sox_loop_sustain_decay) /* AIFF style, one sustain & one decay loop = 64 */
+/**
+Client API:
+Callback called while flow is running (called once per buffer),
+used by sox_flow_effects.callback.
+@returns SOX_SUCCESS to continue, other value to abort flow.
+*/
+typedef int (LSX_API * sox_flow_effects_callback)(
+ sox_bool all_done,
+ void * client_data
+ );
-/* Looping parameters (out-of-band data) */
-typedef struct sox_loopinfo_t {- sox_uint64_t start; /* first sample */
- sox_uint64_t length; /* length */
- unsigned count; /* number of repeats, 0=forever */
- unsigned char type; /* 0=no, 1=forward, 2=forward/back (see sox_loop_... for valid values) */
-} sox_loopinfo_t;
+/**
+Client API:
+Callback for enumerating the contents of a playlist,
+used by the sox_parse_playlist function.
+@returns SOX_SUCCESS if successful, any other value to abort playlist enumeration.
+*/
+typedef int (LSX_API * sox_playlist_callback_t)(
+ void * callback_data,
+ LSX_PARAM_IN_Z char const * filename
+ );
-/* Instrument parameters */
+/*****************************************************************************
+Structures:
+*****************************************************************************/
-/* vague attempt at generic information for sampler-specific info */
+/**
+Client API:
+Information about a build of libSoX, returned from the sox_version_info
+function.
+*/
+typedef struct sox_version_info_t {+ size_t size; /**< structure size = sizeof(sox_version_info_t) */
+ sox_version_flags_t flags; /**< feature flags = popen | magic | threads | memopen */
+ sox_uint32_t version_code; /**< version number = 0x140400 */
+ char const * version; /**< version string = sox_version(), for example, "14.4.0" */
+ char const * version_extra;/**< version extra info or null = "PACKAGE_EXTRA", for example, "beta" */
+ char const * time; /**< build time = "__DATE__ __TIME__", for example, "Jan 7 2010 03:31:50" */
+ char const * distro; /**< distro or null = "DISTRO", for example, "Debian" */
+ char const * compiler; /**< compiler info or null, for example, "msvc 160040219" */
+ char const * arch; /**< arch, for example, "1248 48 44 L OMP" */
+ /* new info should be added at the end for version backwards-compatibility. */
+} sox_version_info_t;
-/* instrument information */
-typedef struct sox_instrinfo_t{- signed char MIDInote; /* for unity pitch playback */
- signed char MIDIlow; /* MIDI pitch-bend low range */
- signed char MIDIhi; /* MIDI pitch-bend high range */
- unsigned char loopmode; /* 0=no, 1=forward, 2=forward/back (see sox_loop_... values) */
- unsigned nloops; /* number of active loops (max SOX_MAX_NLOOPS) */
-} sox_instrinfo_t;
+/**
+Client API:
+Global parameters (for effects & formats), returned from the sox_get_globals
+function.
+*/
+typedef struct sox_globals_t {+/* public: */
+ unsigned verbosity; /**< messages are only written if globals.verbosity >= message.level */
+ sox_output_message_handler_t output_message_handler; /**< client-specified message output callback */
+ sox_bool repeatable; /**< true to use pre-determined timestamps and PRNG seed */
-/* File buffer info. Holds info so that data can be read in blocks. */
-typedef struct sox_fileinfo_t {- char *buf; /* Pointer to data buffer */
- size_t size; /* Size of buffer in bytes */
- size_t count; /* Count read into buffer */
- size_t pos; /* Position in buffer */
-} sox_fileinfo_t;
+ /**
+ Default size (in bytes) used by libSoX for blocks of sample data.
+ Plugins should use similarly-sized buffers to get best performance.
+ */
+ size_t bufsiz;
+ /**
+ Default size (in bytes) used by libSoX for blocks of input sample data.
+ Plugins should use similarly-sized buffers to get best performance.
+ */
+ size_t input_bufsiz;
-typedef struct sox_format_t sox_format_t; /* file format definition */
+ sox_int32_t ranqd1; /**< Can be used to re-seed libSoX's PRNG */
-/* Handler structure defined by each format. */
-typedef struct sox_format_handler_t {- unsigned sox_lib_version_code; /* Checked on load; must be 1st in struct*/
- char const * description; /* short description of format */
- char const * const * names; /* null-terminated array of filename extensions that are handled by this format */
- unsigned int flags; /* File flags (SOX_FILE_...) */
+ char const * stdin_in_use_by; /**< Private: tracks the name of the handler currently using stdin */
+ char const * stdout_in_use_by; /**< Private: tracks the name of the handler currently using stdout */
+ char const * subsystem; /**< Private: tracks the name of the handler currently writing an output message */
+ char * tmp_path; /**< Private: client-configured path to use for temporary files */
+ sox_bool use_magic; /**< Private: true if client has requested use of 'magic' file-type detection */
+ sox_bool use_threads; /**< Private: true if client has requested parallel effects processing */
+} sox_globals_t;
- /* called to initialize reader (decoder) */
- int (SOX_API*startread)( /* Returns SOX_SUCCESS if successful */
- LSX_PARAM_INOUT sox_format_t * ft);
+/**
+Client API:
+Signal parameters; members should be set to SOX_UNSPEC (= 0) if unknown.
+*/
+typedef struct sox_signalinfo_t {+ sox_rate_t rate; /**< samples per second, 0 if unknown */
+ unsigned channels; /**< number of sound channels, 0 if unknown */
+ unsigned precision; /**< bits per sample, 0 if unknown */
+ sox_uint64_t length; /**< samples * chans in file, 0 if unknown, -1 if unspecified */
+ double * mult; /**< Effects headroom multiplier; may be null */
+} sox_signalinfo_t;
- /* called to read (decode) a block of samples */
- size_t (SOX_API*read)( /* Returns number of samples read, or 0 if unsuccessful */
- LSX_PARAM_INOUT sox_format_t * ft,
- LSX_PARAM_OUT_CAP_POST_COUNT(len,return) sox_sample_t *buf,
- size_t len);
+/**
+Client API:
+Basic information about an encoding.
+*/
+typedef struct sox_encodings_info_t {+ sox_encodings_flags_t flags; /**< lossy once (lossy1), lossy twice (lossy2), or lossless (none). */
+ char const * name; /**< encoding name. */
+ char const * desc; /**< encoding description. */
+} sox_encodings_info_t;
- /* called to close reader (decoder); may be null if no closing necessary */
- int (SOX_API*stopread)( /* Returns SOX_SUCCESS if successful */
- LSX_PARAM_INOUT sox_format_t * ft);
+/**
+Client API:
+Encoding parameters.
+*/
+typedef struct sox_encodinginfo_t {+ sox_encoding_t encoding; /**< format of sample numbers */
+ unsigned bits_per_sample;/**< 0 if unknown or variable; uncompressed value if lossless; compressed value if lossy */
+ double compression; /**< compression factor (where applicable) */
- /* called to initialize writer (encoder) */
- int (SOX_API*startwrite)( /* Returns SOX_SUCCESS if successful */
- LSX_PARAM_INOUT sox_format_t * ft);
+ /**
+ Should bytes be reversed? If this is default during sox_open_read or
+ sox_open_write, libSoX will set them to either no or yes according to the
+ machine or format default.
+ */
+ sox_option_t reverse_bytes;
- /* called to write (encode) a block of samples */
- size_t (SOX_API*write)( /* Returns number of samples written, or 0 if unsuccessful */
- LSX_PARAM_INOUT sox_format_t * ft,
- LSX_PARAM_IN_COUNT(len) const sox_sample_t *buf,
- size_t len);
+ /**
+ Should nibbles be reversed? If this is default during sox_open_read or
+ sox_open_write, libSoX will set them to either no or yes according to the
+ machine or format default.
+ */
+ sox_option_t reverse_nibbles;
- /* called to close writer (decoder); may be null if no closing necessary */
- int (SOX_API*stopwrite)( /* Returns SOX_SUCCESS if successful */
- LSX_PARAM_INOUT sox_format_t * ft);
+ /**
+ Should bits be reversed? If this is default during sox_open_read or
+ sox_open_write, libSoX will set them to either no or yes according to the
+ machine or format default.
+ */
+ sox_option_t reverse_bits;
- /* called to reposition reader; may be null if not supported */
- int (SOX_API*seek)( /* Returns SOX_SUCCESS if successful */
- LSX_PARAM_INOUT sox_format_t * ft,
- sox_uint64_t offset);
+ /**
+ If set to true, the format should reverse its default endianness.
+ */
+ sox_bool opposite_endian;
+} sox_encodinginfo_t;
- /* Array of values indicating the encodings and precisions supported for
- * writing (encoding). Precisions specified with default precision first.
- * Encoding, precision, precision, ..., 0, repeat. End with one more 0.
- * Example:
- * unsigned const* formats = {- * SOX_ENCODING_SIGN2, 16, 24, 0, // Support SIGN2 at 16 and 24 bits, default to 16 bits.
- * SOX_ENCODING_UNSIGNED, 8, 0, // Support UNSIGNED at 8 bits, default to 8 bits.
- * 0 // No more supported encodings.
- * };
- */
- unsigned const * write_formats;
+/**
+Client API:
+Looping parameters (out-of-band data).
+*/
+typedef struct sox_loopinfo_t {+ sox_uint64_t start; /**< first sample */
+ sox_uint64_t length; /**< length */
+ unsigned count; /**< number of repeats, 0=forever */
+ unsigned char type; /**< 0=no, 1=forward, 2=forward/back (see sox_loop_* for valid values). */
+} sox_loopinfo_t;
- /* Array of sample rates (samples per second) supported for writing (encoding).
- * NULL if all (or almost all) rates are supported. End with 0. */
- sox_rate_t const * write_rates;
+/**
+Client API:
+Instrument information.
+*/
+typedef struct sox_instrinfo_t{+ signed char MIDInote; /**< for unity pitch playback */
+ signed char MIDIlow; /**< MIDI pitch-bend low range */
+ signed char MIDIhi; /**< MIDI pitch-bend high range */
+ unsigned char loopmode; /**< 0=no, 1=forward, 2=forward/back (see sox_loop_* values) */
+ unsigned nloops; /**< number of active loops (max SOX_MAX_NLOOPS). */
+} sox_instrinfo_t;
- /* SoX will automatically allocate a buffer in which the handler can store data.
- * Specify the size of the buffer needed here. Usually this will be sizeof(your_struct).
- * The buffer will be allocated and zeroed before the call to startread/startwrite.
- * The buffer will be freed after the call to stopread/stopwrite.
- * The buffer will be provided via format.priv in each call to the handler. */
- size_t priv_size;
-} sox_format_handler_t;
+/**
+Client API:
+File buffer info. Holds info so that data can be read in blocks.
+*/
+typedef struct sox_fileinfo_t {+ char *buf; /**< Pointer to data buffer */
+ size_t size; /**< Size of buffer in bytes */
+ size_t count; /**< Count read into buffer */
+ size_t pos; /**< Position in buffer */
+} sox_fileinfo_t;
-/*
- * Format information for input and output files.
- */
+/**
+Client API:
+Handler structure defined by each format.
+*/
+struct sox_format_handler_t {+ unsigned sox_lib_version_code; /**< Checked on load; must be 1st in struct*/
+ char const * description; /**< short description of format */
+ char const * const * names; /**< null-terminated array of filename extensions that are handled by this format */
+ unsigned int flags; /**< File flags (SOX_FILE_* values). */
+ sox_format_handler_startread startread; /**< called to initialize reader (decoder) */
+ sox_format_handler_read read; /**< called to read (decode) a block of samples */
+ sox_format_handler_stopread stopread; /**< called to close reader (decoder); may be null if no closing necessary */
+ sox_format_handler_startwrite startwrite; /**< called to initialize writer (encoder) */
+ sox_format_handler_write write; /**< called to write (encode) a block of samples */
+ sox_format_handler_stopwrite stopwrite; /**< called to close writer (decoder); may be null if no closing necessary */
+ sox_format_handler_seek seek; /**< called to reposition reader; may be null if not supported */
-/* File's metadata. Access via sox_..._comments functions. */
-typedef char * * sox_comments_t;
+ /**
+ Array of values indicating the encodings and precisions supported for
+ writing (encoding). Precisions specified with default precision first.
+ Encoding, precision, precision, ..., 0, repeat. End with one more 0.
+ Example:
+ unsigned const * formats = {+ SOX_ENCODING_SIGN2, 16, 24, 0, // Support SIGN2 at 16 and 24 bits, default to 16 bits.
+ SOX_ENCODING_UNSIGNED, 8, 0, // Support UNSIGNED at 8 bits, default to 8 bits.
+ 0 // No more supported encodings.
+ };
+ */
+ unsigned const * write_formats;
-/* Returns the number of items in the metadata block. */
-size_t
-SOX_API sox_num_comments(
- LSX_PARAM_IN_OPT sox_comments_t comments); /* _In_opt_ */
+ /**
+ Array of sample rates (samples per second) supported for writing (encoding).
+ NULL if all (or almost all) rates are supported. End with 0.
+ */
+ sox_rate_t const * write_rates;
-/* Adds an "id=value" item to the metadata block. */
-void
-SOX_API sox_append_comment(
- LSX_PARAM_DEREF_PRE_MAYBENULL LSX_PARAM_DEREF_POST_NOTNULL sox_comments_t * comments, /* Metadata block pointer. */
- LSX_PARAM_IN_Z char const * item); /* Item to be added. */
+ /**
+ SoX will automatically allocate a buffer in which the handler can store data.
+ Specify the size of the buffer needed here. Usually this will be sizeof(your_struct).
+ The buffer will be allocated and zeroed before the call to startread/startwrite.
+ The buffer will be freed after the call to stopread/stopwrite.
+ The buffer will be provided via format.priv in each call to the handler.
+ */
+ size_t priv_size;
+};
-/* Adds a newline-delimited list of "id=value" items to the metadata block. */
-void
-SOX_API sox_append_comments(
- LSX_PARAM_DEREF_PRE_MAYBENULL LSX_PARAM_DEREF_POST_NOTNULL sox_comments_t * comments, /* Metadata block pointer. */
- LSX_PARAM_IN_Z char const * items); /* Newline-separated list of items to be added. */
-
-/* Duplicates the metadata block. */
-LSX_RETURN_OPT sox_comments_t /* Copied metadata block. */
-SOX_API sox_copy_comments(
- LSX_PARAM_IN_OPT sox_comments_t comments); /* Metadata block to copy. */
-
-/* Frees the metadata block. */
-void
-SOX_API sox_delete_comments(
- LSX_PARAM_DEREF_PRE_MAYBENULL LSX_PARAM_DEREF_POST_NULL sox_comments_t * comments);
-
-/* If "id=value" is found, return value, else return null. */
-char const * /* _Ret_opt_z_: Value if found, else null. */
-SOX_API sox_find_comment(
- LSX_PARAM_IN_OPT sox_comments_t comments, /* Metadata block in which to search. */
- LSX_PARAM_IN_Z char const * id); /* Id for which to search */
-
-#define SOX_MAX_NLOOPS 8
-
-/* comments, instrument info, loop info (out-of-band data) */
+/**
+Client API:
+Comments, instrument info, loop info (out-of-band data).
+*/
typedef struct sox_oob_t{/* Decoded: */
- sox_comments_t comments; /* Comment strings in id=value format. */
- sox_instrinfo_t instr; /* Instrument specification */
- sox_loopinfo_t loops[SOX_MAX_NLOOPS]; /* Looping specification */
+ sox_comments_t comments; /**< Comment strings in id=value format. */
+ sox_instrinfo_t instr; /**< Instrument specification */
+ sox_loopinfo_t loops[SOX_MAX_NLOOPS]; /**< Looping specification */
/* TBD: Non-decoded chunks, etc: */
} sox_oob_t;
-/* Is file a real file, a pipe, or a url? */
-typedef enum lsx_io_type
-{- lsx_io_file,
- lsx_io_pipe,
- lsx_io_url
-} lsx_io_type;
-
-struct sox_format_t { /* Data passed to/from the format handler */- char * filename; /* File name */
+/**
+Client API:
+Data passed to/from the format handler
+*/
+struct sox_format_t {+ char * filename; /**< File name */
- /* Signal specifications for reader (decoder) or writer (encoder):
- * sample rate, #channels, precision, length, headroom multiplier.
- * Any info specified by the user is here on entry to startread or
- * startwrite. Info will be SOX_UNSPEC if the user provided no info.
- * At exit from startread, should be completely filled in, using
- * either data from the file's headers (if available) or whatever
- * the format is guessing/assuming (if header data is not available).
- * At exit from startwrite, should be completely filled in, using
- * either the data that was specified, or values chosen by the format
- * based on the format's defaults or capabilities. */
+ /**
+ Signal specifications for reader (decoder) or writer (encoder):
+ sample rate, number of channels, precision, length, headroom multiplier.
+ Any info specified by the user is here on entry to startread or
+ startwrite. Info will be SOX_UNSPEC if the user provided no info.
+ At exit from startread, should be completely filled in, using
+ either data from the file's headers (if available) or whatever
+ the format is guessing/assuming (if header data is not available).
+ At exit from startwrite, should be completely filled in, using
+ either the data that was specified, or values chosen by the format
+ based on the format's defaults or capabilities.
+ */
sox_signalinfo_t signal;
- /* Encoding specifications for reader (decoder) or writer (encoder):
- * encoding (sample format), bits per sample, compression rate, endianness.
- * Should be filled in by startread. Values specified should be used
- * by startwrite when it is configuring the encoding parameters. */
+ /**
+ Encoding specifications for reader (decoder) or writer (encoder):
+ encoding (sample format), bits per sample, compression rate, endianness.
+ Should be filled in by startread. Values specified should be used
+ by startwrite when it is configuring the encoding parameters.
+ */
sox_encodinginfo_t encoding;
- char * filetype; /* Type of file, as determined by header inspection or libmagic. */
- sox_oob_t oob; /* comments, instrument info, loop info (out-of-band data) */
- sox_bool seekable; /* Can seek on this file */
- char mode; /* Read or write mode ('r' or 'w') */- sox_uint64_t olength; /* Samples * chans written to file */
- size_t clips; /* Incremented if clipping occurs */
- int sox_errno; /* Failure error code */
- char sox_errstr[256]; /* Failure error text */
- void * fp; /* File stream pointer */
- lsx_io_type io_type; /* Stores whether this is a file, pipe or URL */
- sox_uint64_t tell_off; /* Current offset within file */
- sox_uint64_t data_start; /* Offset at which headers end and sound data begins (set by lsx_check_read_params) */
- sox_format_handler_t handler; /* Format handler for this file */
- void * priv; /* Format handler's private data area */
+ char * filetype; /**< Type of file, as determined by header inspection or libmagic. */
+ sox_oob_t oob; /**< comments, instrument info, loop info (out-of-band data) */
+ sox_bool seekable; /**< Can seek on this file */
+ char mode; /**< Read or write mode ('r' or 'w') */+ sox_uint64_t olength; /**< Samples * chans written to file */
+ size_t clips; /**< Incremented if clipping occurs */
+ int sox_errno; /**< Failure error code */
+ char sox_errstr[256]; /**< Failure error text */
+ void * fp; /**< File stream pointer */
+ lsx_io_type io_type; /**< Stores whether this is a file, pipe or URL */
+ sox_uint64_t tell_off; /**< Current offset within file */
+ sox_uint64_t data_start; /**< Offset at which headers end and sound data begins (set by lsx_check_read_params) */
+ sox_format_handler_t handler; /**< Format handler for this file */
+ void * priv; /**< Format handler's private data area */
};
-/* File flags field */
-#define SOX_FILE_NOSTDIO 0x0001 /* Does not use stdio routines */
-#define SOX_FILE_DEVICE 0x0002 /* File is an audio device */
-#define SOX_FILE_PHONY 0x0004 /* Phony file/device (i.e. nulfile) */
-#define SOX_FILE_REWIND 0x0008 /* File should be rewound to write header */
-#define SOX_FILE_BIT_REV 0x0010 /* Is file bit-reversed? */
-#define SOX_FILE_NIB_REV 0x0020 /* Is file nibble-reversed? */
-#define SOX_FILE_ENDIAN 0x0040 /* Is file format endian? */
-#define SOX_FILE_ENDBIG 0x0080 /* For endian file format, is it big endian? */
-#define SOX_FILE_MONO 0x0100 /* Do channel restrictions allow mono? */
-#define SOX_FILE_STEREO 0x0200 /* Do channel restrictions allow stereo? */
-#define SOX_FILE_QUAD 0x0400 /* Do channel restrictions allow quad? */
+/**
+Client API:
+Information about a loaded format handler, including the format name and a
+function pointer that can be invoked to get additional information about the
+format.
+*/
+typedef struct sox_format_tab_t {+ char *name; /**< Name of format handler */
+ sox_format_fn_t fn; /**< Function to call to get format handler's information */
+} sox_format_tab_t;
-#define SOX_FILE_CHANS (SOX_FILE_MONO | SOX_FILE_STEREO | SOX_FILE_QUAD) /* No channel restrictions */
-#define SOX_FILE_LIT_END (SOX_FILE_ENDIAN | 0) /* File is little-endian */
-#define SOX_FILE_BIG_END (SOX_FILE_ENDIAN | SOX_FILE_ENDBIG) /* File is big-endian */
+/**
+Client API:
+Global parameters for effects.
+*/
+typedef struct sox_effects_globals_t {+ sox_plot_t plot; /**< To help the user choose effect & options */
+ sox_globals_t * global_info; /**< Pointer to associated SoX globals */
+} sox_effects_globals_t;
-/* Find & load format handler plugins. */
-int /* Returns SOX_SUCCESS if successful */
-SOX_API sox_format_init(void);
+/**
+Client API:
+Effect handler information.
+*/
+struct sox_effect_handler_t {+ char const * name; /**< Effect name */
+ char const * usage; /**< Short explanation of parameters accepted by effect */
+ unsigned int flags; /**< Combination of SOX_EFF_* flags */
+ sox_effect_handler_getopts getopts; /**< Called to parse command-line arguments (called once per effect). */
+ sox_effect_handler_start start; /**< Called to initialize effect (called once per flow). */
+ sox_effect_handler_flow flow; /**< Called to process samples. */
+ sox_effect_handler_drain drain; /**< Called to finish getting output after input is complete. */
+ sox_effect_handler_stop stop; /**< Called to shut down effect (called once per flow). */
+ sox_effect_handler_kill kill; /**< Called to shut down effect (called once per effect). */
+ size_t priv_size; /**< Size of private data SoX should pre-allocate for effect */
+};
-/* Unload format handler plugins. */
-void
-SOX_API sox_format_quit(void);
+/**
+Client API:
+Effect information.
+*/
+struct sox_effect_t {+ sox_effects_globals_t * global_info; /**< global effect parameters */
+ sox_signalinfo_t in_signal; /**< Information about the incoming data stream */
+ sox_signalinfo_t out_signal; /**< Information about the outgoing data stream */
+ sox_encodinginfo_t const * in_encoding; /**< Information about the incoming data encoding */
+ sox_encodinginfo_t const * out_encoding; /**< Information about the outgoing data encoding */
+ sox_effect_handler_t handler; /**< The handler for this effect */
+ sox_sample_t * obuf; /**< output buffer */
+ size_t obeg; /**< output buffer consumed */
+ size_t oend; /**< output buffer total length */
+ size_t imin; /**< minimum input buffer size */
+ size_t clips; /**< increment if clipping occurs */
+ size_t flows; /**< 1 if MCHAN, number of chans otherwise */
+ size_t flow; /**< flow number */
+ void * priv; /**< Effect's private data area */
+};
-/* Initialize effects library. */
-int /* Returns SOX_SUCCESS if successful */
-SOX_API sox_init(void);
+/**
+Client API:
+Chain of effects to be applied to a stream.
+*/
+typedef struct sox_effects_chain_t {+ sox_effect_t **effects; /**< Table of effects to be applied to a stream */
+ unsigned table_size; /**< Number of entries in effects table */
+ unsigned length; /**< Number of effects to be applied */
+ sox_sample_t **ibufc; /**< Channel interleave buffer */
+ sox_sample_t **obufc; /**< Channel interleave buffer */
+ sox_effects_globals_t global_info; /**< Copy of global effects settings */
+ sox_encodinginfo_t const * in_enc; /**< Input encoding */
+ sox_encodinginfo_t const * out_enc; /**< Output encoding */
+} sox_effects_chain_t;
-/* Close effects library and unload format handler plugins. */
-int /* Returns SOX_SUCCESS if successful */
-SOX_API sox_quit(void);
+/*****************************************************************************
+Functions:
+*****************************************************************************/
-/* callback to retrieve information about a format handler */
-typedef const sox_format_handler_t *(SOX_API *sox_format_fn_t)(void);
+/**
+Client API:
+Returns version number string of libSoX, for example, "14.4.0".
+@returns The version number string of libSoX, for example, "14.4.0".
+*/
+LSX_RETURN_VALID_Z LSX_RETURN_PURE
+char const *
+LSX_API
+sox_version(void);
-/* Information about a loaded format handler: name and function pointer */
-typedef struct sox_format_tab_t {- char *name; /* Name of format handler */
- sox_format_fn_t fn; /* Function to call to get format handler's information */
-} sox_format_tab_t;
+/**
+Client API:
+Returns information about this build of libsox.
+@returns Pointer to a version information structure.
+*/
+LSX_RETURN_VALID LSX_RETURN_PURE
+sox_version_info_t const *
+LSX_API
+sox_version_info(void);
-/* Returns the table of format handler names and functions */
-LSX_RETURN_ARRAY LSX_RETURN_PURE sox_format_tab_t const *
-SOX_API sox_get_format_fns(void);
+/**
+Client API:
+Returns a pointer to the structure with libSoX's global settings.
+@returns a pointer to the structure with libSoX's global settings.
+*/
+LSX_RETURN_VALID LSX_RETURN_PURE
+sox_globals_t *
+LSX_API
+sox_get_globals(void);
-#define sox_format_fns (sox_get_format_fns())
+/**
+Client API:
+Deprecated macro that returns the structure with libSoX's global settings
+as an lvalue.
+*/
+#define sox_globals (*sox_get_globals())
-/* Opens a decoding session for a file. Returned handle must be closed with sox_close(). */
-LSX_RETURN_OPT sox_format_t * /* Returns NULL on failure. */
-SOX_API sox_open_read(
- LSX_PARAM_IN_Z char const * path, /* Path to file to be opened (required). */
- LSX_PARAM_IN_OPT sox_signalinfo_t const * signal, /* Information already known about audio stream, or NULL if none. */
- LSX_PARAM_IN_OPT sox_encodinginfo_t const * encoding, /* Information already known about sample encoding, or NULL if none. */
- LSX_PARAM_IN_OPT_Z char const * filetype); /* Previously-determined file type, or NULL to auto-detect. */
+/**
+Client API:
+Returns a pointer to the list of available encodings.
+End of list indicated by name == NULL.
+@returns pointer to the list of available encodings.
+*/
+LSX_RETURN_ARRAY LSX_RETURN_PURE
+sox_encodings_info_t const *
+LSX_API
+sox_get_encodings_info(void);
-/* Opens a decoding session for a memory buffer. Returned handle must be closed with sox_close(). */
-LSX_RETURN_OPT sox_format_t * /* Returns NULL on failure. */
-SOX_API sox_open_mem_read(
- LSX_PARAM_IN_BYTECOUNT(buffer_size) void * buffer, /* Pointer to audio data buffer (required). */
- size_t buffer_size,/* Number of bytes to read from audio data buffer. */
- LSX_PARAM_IN_OPT sox_signalinfo_t const * signal, /* Information already known about audio stream, or NULL if none. */
- LSX_PARAM_IN_OPT sox_encodinginfo_t const * encoding, /* Information already known about sample encoding, or NULL if none. */
- LSX_PARAM_IN_OPT_Z char const * filetype); /* Previously-determined file type, or NULL to auto-detect. */
+/**
+Client API:
+Deprecated macro that returns the list of available encodings.
+End of list indicated by name == NULL.
+*/
+#define sox_encodings_info (sox_get_encodings_info())
-/* Returns true if the format handler for the specified file type supports the specified encoding. */
-sox_bool
-SOX_API sox_format_supports_encoding(
- LSX_PARAM_IN_OPT_Z char const * path, /* Path to file to be examined (required if filetype is NULL). */
- LSX_PARAM_IN_OPT_Z char const * filetype, /* Previously-determined file type, or NULL to use extension from path. */
- LSX_PARAM_IN sox_encodinginfo_t const * encoding); /* Encoding for which format handler should be queried. */
+/**
+Client API:
+Fills in an encodinginfo with default values.
+*/
+void
+LSX_API
+sox_init_encodinginfo(
+ LSX_PARAM_OUT sox_encodinginfo_t * e /**< Pointer to uninitialized encoding info structure to be initialized. */
+ );
-/* Gets the format handler for a specified file type. */
-LSX_RETURN_OPT sox_format_handler_t const * /* Returns NULL on failure. */
-SOX_API sox_write_handler(
- LSX_PARAM_IN_OPT_Z char const * path, /* Path to file (required if filetype is NULL). */
- LSX_PARAM_IN_OPT_Z char const * filetype, /* Filetype for which handler is needed, or NULL to use extension from path. */
- LSX_PARAM_OUT_OPT char const * * filetype1); /* Receives the filetype that was detected. Pass NULL if not needed. */
+/**
+Client API:
+Given an encoding (for example, SIGN2) and the encoded bits_per_sample (for
+example, 16), returns the number of useful bits per sample in the decoded data
+(for example, 16), or returns 0 to indicate that the value returned by the
+format handler should be used instead of a pre-determined precision.
+@returns the number of useful bits per sample in the decoded data (for example
+16), or returns 0 to indicate that the value returned by the format handler
+should be used instead of a pre-determined precision.
+*/
+LSX_RETURN_PURE
+unsigned
+LSX_API
+sox_precision(
+ sox_encoding_t encoding, /**< Encoding for which to lookup precision information. */
+ unsigned bits_per_sample /**< The number of encoded bits per sample. */
+ );
-/* Opens an encoding session for a file. Returned handle must be closed with sox_close(). */
-LSX_RETURN_OPT sox_format_t * /* Returns NULL on failure. */
-SOX_API sox_open_write(
- LSX_PARAM_IN_Z char const * path, /* Path to file to be written (required). */
- LSX_PARAM_IN sox_signalinfo_t const * signal, /* Information about desired audio stream (required). */
- LSX_PARAM_IN_OPT sox_encodinginfo_t const * encoding, /* Information about desired sample encoding, or NULL to use defaults. */
- LSX_PARAM_IN_OPT_Z char const * filetype, /* Previously-determined file type, or NULL to auto-detect. */
- LSX_PARAM_IN_OPT sox_oob_t const * oob, /* Out-of-band data to add to file, or NULL if none. */
- LSX_PARAM_IN_OPT sox_bool (SOX_API*overwrite_permitted)(LSX_PARAM_IN_Z const char *filename)); /* Called if file exists to determine whether overwrite is ok. */
+/**
+Client API:
+Returns the number of items in the metadata block.
+@returns the number of items in the metadata block.
+*/
+size_t
+LSX_API
+sox_num_comments(
+ LSX_PARAM_IN_OPT sox_comments_t comments /**< Metadata block. */
+ );
-/* Opens an encoding session for a memory buffer. Returned handle must be closed with sox_close(). */
-LSX_RETURN_OPT sox_format_t * /* Returns NULL on failure. */
-SOX_API sox_open_mem_write(
- LSX_PARAM_OUT_BYTECAP(buffer_size) void * buffer, /* Pointer to audio data buffer that receives data (required). */
- LSX_PARAM_IN size_t buffer_size, /* Maximum number of bytes to write to audio data buffer. */
- LSX_PARAM_IN sox_signalinfo_t const * signal, /* Information about desired audio stream (required). */
- LSX_PARAM_IN_OPT sox_encodinginfo_t const * encoding, /* Information about desired sample encoding, or NULL to use defaults. */
- LSX_PARAM_IN_OPT_Z char const * filetype, /* Previously-determined file type, or NULL to auto-detect. */
- LSX_PARAM_IN_OPT sox_oob_t const * oob); /* Out-of-band data to add to file, or NULL if none. */
+/**
+Client API:
+Adds an "id=value" item to the metadata block.
+*/
+void
+LSX_API
+sox_append_comment(
+ LSX_PARAM_DEREF_PRE_MAYBENULL LSX_PARAM_DEREF_POST_NOTNULL sox_comments_t * comments, /**< Metadata block. */
+ LSX_PARAM_IN_Z char const * item /**< Item to be added in "id=value" format. */
+ );
-/* Opens an encoding session for a memstream buffer. Returned handle must be closed with sox_close(). */
-LSX_RETURN_OPT sox_format_t * /* Returns NULL on failure. */
-SOX_API sox_open_memstream_write(
- LSX_PARAM_OUT char * * buffer_ptr, /* Receives pointer to audio data buffer that receives data (required). */
- LSX_PARAM_OUT size_t * buffer_size_ptr, /* Receives size of data written to audio data buffer (required). */
- LSX_PARAM_IN sox_signalinfo_t const * signal, /* Information about desired audio stream (required). */
- LSX_PARAM_IN_OPT sox_encodinginfo_t const * encoding, /* Information about desired sample encoding, or NULL to use defaults. */
- LSX_PARAM_IN_OPT_Z char const * filetype, /* Previously-determined file type, or NULL to auto-detect. */
- LSX_PARAM_IN_OPT sox_oob_t const * oob); /* Out-of-band data to add to file, or NULL if none. */
+/**
+Client API:
+Adds a newline-delimited list of "id=value" items to the metadata block.
+*/
+void
+LSX_API
+sox_append_comments(
+ LSX_PARAM_DEREF_PRE_MAYBENULL LSX_PARAM_DEREF_POST_NOTNULL sox_comments_t * comments, /**< Metadata block. */
+ LSX_PARAM_IN_Z char const * items /**< Newline-separated list of items to be added, for example "id1=value1\\nid2=value2". */
+ );
-/* Reads samples from a decoding session into a sample buffer. Returns # of samples decoded, or 0 for EOF. */
-size_t
-SOX_API sox_read(
- LSX_PARAM_INOUT sox_format_t * ft,
- LSX_PARAM_OUT_CAP_POST_COUNT(len,return) sox_sample_t *buf,
- size_t len);
+/**
+Client API:
+Duplicates the metadata block.
+@returns the copied metadata block.
+*/
+LSX_RETURN_OPT
+sox_comments_t
+LSX_API
+sox_copy_comments(
+ LSX_PARAM_IN_OPT sox_comments_t comments /**< Metadata block to copy. */
+ );
-/* Writes samples to an encoding session from a sample buffer. Returns # of samples encoded. */
-size_t
-SOX_API sox_write(
- LSX_PARAM_INOUT sox_format_t * ft,
- LSX_PARAM_IN_COUNT(len) const sox_sample_t *buf,
- size_t len);
+/**
+Client API:
+Frees the metadata block.
+*/
+void
+LSX_API
+sox_delete_comments(
+ LSX_PARAM_DEREF_PRE_MAYBENULL LSX_PARAM_DEREF_POST_NULL sox_comments_t * comments /**< Metadata block. */
+ );
-/* Closes an encoding or decoding session. */
-int /* Returns SOX_SUCCESS if successful */
-SOX_API sox_close(
- LSX_PARAM_INOUT sox_format_t * ft);
+/**
+Client API:
+If "id=value" is found, return value, else return null.
+@returns value, or null if value not found.
+*/
+LSX_RETURN_OPT
+char const *
+LSX_API
+sox_find_comment(
+ LSX_PARAM_IN_OPT sox_comments_t comments, /**< Metadata block in which to search. */
+ LSX_PARAM_IN_Z char const * id /**< Id for which to search */
+ );
-#define SOX_SEEK_SET 0
+/**
+Client API:
+Find and load format handler plugins.
+@returns SOX_SUCCESS if successful.
+*/
+int
+LSX_API
+sox_format_init(void);
-/* Sets the location at which next samples will be decoded. Returns SOX_SUCCESS if successful. */
-int /* Returns SOX_SUCCESS if successful */
-SOX_API sox_seek(
- LSX_PARAM_INOUT sox_format_t * ft,
- sox_uint64_t offset,
- int whence);
+/**
+Client API:
+Unload format handler plugins.
+*/
+void
+LSX_API
+sox_format_quit(void);
-/* Finds a format handler by name. */
-LSX_RETURN_OPT sox_format_handler_t const *
-SOX_API sox_find_format(
- LSX_PARAM_IN_Z char const * name,
- sox_bool ignore_devices);
+/**
+Client API:
+Initialize effects library.
+@returns SOX_SUCCESS if successful.
+*/
+int
+LSX_API
+sox_init(void);
-/*
- * Structures for effects.
- */
+/**
+Client API:
+Close effects library and unload format handler plugins.
+@returns SOX_SUCCESS if successful.
+*/
+int
+LSX_API
+sox_quit(void);
-#define SOX_EFF_CHAN 1 /* Effect might alter the number of channels */
-#define SOX_EFF_RATE 2 /* Effect might alter sample rate */
-#define SOX_EFF_PREC 4 /* Effect might alter sample precision */
-#define SOX_EFF_LENGTH 8 /* Effect might alter audio length */
-#define SOX_EFF_MCHAN 16 /* Effect handles multiple channels internally */
-#define SOX_EFF_NULL 32 /* Effect does nothing (can be optimized out of flow) */
-#define SOX_EFF_DEPRECATED 64 /* Effect will soon be removed from SoX */
-#define SOX_EFF_GAIN 128 /* Effect does not support gain -r */
-#define SOX_EFF_MODIFY 256 /* Effect does not modify samples (just watches as data goes through) */
-#define SOX_EFF_ALPHA 512 /* Effect is experimental/incomplete */
-#define SOX_EFF_INTERNAL 1024 /* Effect present libSoX but not valid for use by SoX command-line tools */
+/**
+Client API:
+Returns the table of format handler names and functions.
+@returns the table of format handler names and functions.
+*/
+LSX_RETURN_ARRAY LSX_RETURN_PURE
+sox_format_tab_t const *
+LSX_API
+sox_get_format_fns(void);
-typedef enum sox_plot_t {- sox_plot_off,
- sox_plot_octave,
- sox_plot_gnuplot,
- sox_plot_data
-} sox_plot_t;
+/**
+Client API:
+Deprecated macro that returns the table of format handler names and functions.
+*/
+#define sox_format_fns (sox_get_format_fns())
-typedef struct sox_effect_t sox_effect_t;
+/**
+Client API:
+Opens a decoding session for a file. Returned handle must be closed with sox_close().
+@returns The handle for the new session, or null on failure.
+*/
+LSX_RETURN_OPT
+sox_format_t *
+LSX_API
+sox_open_read(
+ LSX_PARAM_IN_Z char const * path, /**< Path to file to be opened (required). */
+ LSX_PARAM_IN_OPT sox_signalinfo_t const * signal, /**< Information already known about audio stream, or NULL if none. */
+ LSX_PARAM_IN_OPT sox_encodinginfo_t const * encoding, /**< Information already known about sample encoding, or NULL if none. */
+ LSX_PARAM_IN_OPT_Z char const * filetype /**< Previously-determined file type, or NULL to auto-detect. */
+ );
-/* Global parameters for effects */
-typedef struct sox_effects_globals_t {- sox_plot_t plot; /* To help the user choose effect & options */
- sox_globals_t * global_info; /* Pointer to associated SoX globals */
-} sox_effects_globals_t;
+/**
+Client API:
+Opens a decoding session for a memory buffer. Returned handle must be closed with sox_close().
+@returns The handle for the new session, or null on failure.
+*/
+LSX_RETURN_OPT
+sox_format_t *
+LSX_API
+sox_open_mem_read(
+ LSX_PARAM_IN_BYTECOUNT(buffer_size) void * buffer, /**< Pointer to audio data buffer (required). */
+ size_t buffer_size,/**< Number of bytes to read from audio data buffer. */
+ LSX_PARAM_IN_OPT sox_signalinfo_t const * signal, /**< Information already known about audio stream, or NULL if none. */
+ LSX_PARAM_IN_OPT sox_encodinginfo_t const * encoding, /**< Information already known about sample encoding, or NULL if none. */
+ LSX_PARAM_IN_OPT_Z char const * filetype /**< Previously-determined file type, or NULL to auto-detect. */
+ );
-/* Returns global parameters for effects */
-LSX_RETURN_VALID LSX_RETURN_PURE sox_effects_globals_t *
-SOX_API sox_get_effects_globals(void);
+/**
+Client API:
+Returns true if the format handler for the specified file type supports the specified encoding.
+@returns true if the format handler for the specified file type supports the specified encoding.
+*/
+sox_bool
+LSX_API
+sox_format_supports_encoding(
+ LSX_PARAM_IN_OPT_Z char const * path, /**< Path to file to be examined (required if filetype is NULL). */
+ LSX_PARAM_IN_OPT_Z char const * filetype, /**< Previously-determined file type, or NULL to use extension from path. */
+ LSX_PARAM_IN sox_encodinginfo_t const * encoding /**< Encoding for which format handler should be queried. */
+ );
-#define sox_effects_globals (*sox_get_effects_globals())
+/**
+Client API:
+Gets the format handler for a specified file type.
+@returns The found format handler, or null if not found.
+*/
+LSX_RETURN_OPT
+sox_format_handler_t const *
+LSX_API
+sox_write_handler(
+ LSX_PARAM_IN_OPT_Z char const * path, /**< Path to file (required if filetype is NULL). */
+ LSX_PARAM_IN_OPT_Z char const * filetype, /**< Filetype for which handler is needed, or NULL to use extension from path. */
+ LSX_PARAM_OUT_OPT char const * * filetype1 /**< Receives the filetype that was detected. Pass NULL if not needed. */
+ );
-/* Effect handler information */
-typedef struct sox_effect_handler_t {- char const * name; /* Effect name */
- char const * usage; /* Short explanation of parameters accepted by effect */
- unsigned int flags; /* Combination of SOX_EFF_... flags */
+/**
+Client API:
+Opens an encoding session for a file. Returned handle must be closed with sox_close().
+@returns The new session handle, or null on failure.
+*/
+LSX_RETURN_OPT
+sox_format_t *
+LSX_API
+sox_open_write(
+ LSX_PARAM_IN_Z char const * path, /**< Path to file to be written (required). */
+ LSX_PARAM_IN sox_signalinfo_t const * signal, /**< Information about desired audio stream (required). */
+ LSX_PARAM_IN_OPT sox_encodinginfo_t const * encoding, /**< Information about desired sample encoding, or NULL to use defaults. */
+ LSX_PARAM_IN_OPT_Z char const * filetype, /**< Previously-determined file type, or NULL to auto-detect. */
+ LSX_PARAM_IN_OPT sox_oob_t const * oob, /**< Out-of-band data to add to file, or NULL if none. */
+ LSX_PARAM_IN_OPT sox_bool (LSX_API * overwrite_permitted)(LSX_PARAM_IN_Z char const * filename) /**< Called if file exists to determine whether overwrite is ok. */
+ );
- /* Called to parse command-line arguments (called once per effect) */
- int (SOX_API*getopts)( /* Returns SOX_SUCCESS if successful */
- LSX_PARAM_INOUT sox_effect_t * effp,
- int argc,
- LSX_PARAM_IN_COUNT(argc) char *argv[]);
+/**
+Client API:
+Opens an encoding session for a memory buffer. Returned handle must be closed with sox_close().
+@returns The new session handle, or null on failure.
+*/
+LSX_RETURN_OPT
+sox_format_t *
+LSX_API
+sox_open_mem_write(
+ LSX_PARAM_OUT_BYTECAP(buffer_size) void * buffer, /**< Pointer to audio data buffer that receives data (required). */
+ LSX_PARAM_IN size_t buffer_size, /**< Maximum number of bytes to write to audio data buffer. */
+ LSX_PARAM_IN sox_signalinfo_t const * signal, /**< Information about desired audio stream (required). */
+ LSX_PARAM_IN_OPT sox_encodinginfo_t const * encoding, /**< Information about desired sample encoding, or NULL to use defaults. */
+ LSX_PARAM_IN_OPT_Z char const * filetype, /**< Previously-determined file type, or NULL to auto-detect. */
+ LSX_PARAM_IN_OPT sox_oob_t const * oob /**< Out-of-band data to add to file, or NULL if none. */
+ );
- /* Called to initialize effect (called once per flow) */
- int (SOX_API*start)( /* Returns SOX_SUCCESS if successful */
- LSX_PARAM_INOUT sox_effect_t * effp);
+/**
+Client API:
+Opens an encoding session for a memstream buffer. Returned handle must be closed with sox_close().
+@returns The new session handle, or null on failure.
+*/
+LSX_RETURN_OPT
+sox_format_t *
+LSX_API
+sox_open_memstream_write(
+ LSX_PARAM_OUT char * * buffer_ptr, /**< Receives pointer to audio data buffer that receives data (required). */
+ LSX_PARAM_OUT size_t * buffer_size_ptr, /**< Receives size of data written to audio data buffer (required). */
+ LSX_PARAM_IN sox_signalinfo_t const * signal, /**< Information about desired audio stream (required). */
+ LSX_PARAM_IN_OPT sox_encodinginfo_t const * encoding, /**< Information about desired sample encoding, or NULL to use defaults. */
+ LSX_PARAM_IN_OPT_Z char const * filetype, /**< Previously-determined file type, or NULL to auto-detect. */
+ LSX_PARAM_IN_OPT sox_oob_t const * oob /**< Out-of-band data to add to file, or NULL if none. */
+ );
- /* Called to process samples */
- int (SOX_API*flow)( /* Returns SOX_SUCCESS if successful */
- LSX_PARAM_INOUT sox_effect_t * effp,
- LSX_PARAM_IN_COUNT(*isamp) const sox_sample_t *ibuf,
- LSX_PARAM_OUT_CAP_POST_COUNT(*osamp,*osamp) sox_sample_t *obuf,
- LSX_PARAM_INOUT size_t *isamp,
- LSX_PARAM_INOUT size_t *osamp);
+/**
+Client API:
+Reads samples from a decoding session into a sample buffer.
+@returns Number of samples decoded, or 0 for EOF.
+*/
+size_t
+LSX_API
+sox_read(
+ LSX_PARAM_INOUT sox_format_t * ft, /**< Format pointer. */
+ LSX_PARAM_OUT_CAP_POST_COUNT(len,return) sox_sample_t *buf, /**< Buffer from which to read samples. */
+ size_t len /**< Number of samples available in buf. */
+ );
- /* Called to finish getting output after input is complete */
- int (SOX_API*drain)( /* Returns SOX_SUCCESS if successful */
- LSX_PARAM_INOUT sox_effect_t * effp,
- LSX_PARAM_OUT_CAP_POST_COUNT(*osamp,*osamp) sox_sample_t *obuf,
- LSX_PARAM_INOUT size_t *osamp);
+/**
+Client API:
+Writes samples to an encoding session from a sample buffer.
+@returns Number of samples encoded.
+*/
+size_t
+LSX_API
+sox_write(
+ LSX_PARAM_INOUT sox_format_t * ft, /**< Format pointer. */
+ LSX_PARAM_IN_COUNT(len) sox_sample_t const * buf, /**< Buffer from which to read samples. */
+ size_t len /**< Number of samples available in buf. */
+ );
- /* Called to shut down effect (called once per flow) */
- int (SOX_API*stop)( /* Returns SOX_SUCCESS if successful */
- LSX_PARAM_INOUT sox_effect_t * effp);
+/**
+Client API:
+Closes an encoding or decoding session.
+@returns SOX_SUCCESS if successful.
+*/
+int
+LSX_API
+sox_close(
+ LSX_PARAM_INOUT sox_format_t * ft /**< Format pointer. */
+ );
- /* Called to shut down effect (called once per effect) */
- int (SOX_API*kill)( /* Returns SOX_SUCCESS if successful */
- LSX_PARAM_INOUT sox_effect_t * effp);
+/**
+Client API:
+Sets the location at which next samples will be decoded. Returns SOX_SUCCESS if successful.
+@returns SOX_SUCCESS if successful.
+*/
+int
+LSX_API
+sox_seek(
+ LSX_PARAM_INOUT sox_format_t * ft, /**< Format pointer. */
+ sox_uint64_t offset, /**< Sample offset at which to position reader. */
+ int whence /**< Set to SOX_SEEK_SET. */
+ );
- size_t priv_size; /* Size of private data SoX should pre-allocate for effect */
-} sox_effect_handler_t;
+/**
+Client API:
+Finds a format handler by name.
+@returns Format handler data, or null if not found.
+*/
+LSX_RETURN_OPT
+sox_format_handler_t const *
+LSX_API
+sox_find_format(
+ LSX_PARAM_IN_Z char const * name, /**< Name of format handler to find. */
+ sox_bool ignore_devices /**< Set to true to ignore device names. */
+ );
-/* Effect information */
-struct sox_effect_t {- sox_effects_globals_t * global_info; /* global effect parameters */
- sox_signalinfo_t in_signal; /* Information about the incoming data stream */
- sox_signalinfo_t out_signal; /* Information about the outgoing data stream */
- sox_encodinginfo_t const * in_encoding; /* Information about the incoming data encoding */
- sox_encodinginfo_t const * out_encoding; /* Information about the outgoing data encoding */
- sox_effect_handler_t handler; /* The handler for this effect */
- sox_sample_t * obuf; /* output buffer */
- size_t obeg; /* output buffer consumed */
- size_t oend; /* output buffer total length */
- size_t imin; /* minimum input buffer size */
- size_t clips; /* increment if clipping occurs */
- size_t flows; /* 1 if MCHAN, # chans otherwise */
- size_t flow; /* flow # */
- void * priv; /* Effect's private data area */
-};
+/**
+Client API:
+Returns global parameters for effects
+@returns global parameters for effects.
+*/
+LSX_RETURN_VALID LSX_RETURN_PURE
+sox_effects_globals_t *
+LSX_API
+sox_get_effects_globals(void);
-/* Finds the effect handler with the given name */
-LSX_RETURN_OPT LSX_RETURN_PURE sox_effect_handler_t const * /* Returns NULL if unable to find the effect. */
-SOX_API sox_find_effect(
- LSX_PARAM_IN_Z char const * name);
+/**
+Client API:
+Deprecated macro that returns global parameters for effects.
+*/
+#define sox_effects_globals (*sox_get_effects_globals())
-/* Creates an effect using the given handler */
-LSX_RETURN_OPT sox_effect_t * /* Returns NULL if unable to create the effect. */
-SOX_API sox_create_effect(
- LSX_PARAM_IN sox_effect_handler_t const * eh);
+/**
+Client API:
+Finds the effect handler with the given name.
+@returns Effect pointer, or null if not found.
+*/
+LSX_RETURN_OPT LSX_RETURN_PURE
+sox_effect_handler_t const *
+LSX_API
+sox_find_effect(
+ LSX_PARAM_IN_Z char const * name /**< Name of effect to find. */
+ );
-/* Applies the command-line options to the effect. Returns the number of arguments consumed. */
+/**
+Client API:
+Creates an effect using the given handler.
+@returns The new effect, or null if not found.
+*/
+LSX_RETURN_OPT
+sox_effect_t *
+LSX_API
+sox_create_effect(
+ LSX_PARAM_IN sox_effect_handler_t const * eh /**< Handler to use for effect. */
+ );
+
+/**
+Client API:
+Applies the command-line options to the effect.
+@returns the number of arguments consumed.
+*/
int
-SOX_API sox_effect_options(
- LSX_PARAM_IN sox_effect_t *effp,
- int argc,
- LSX_PARAM_IN_COUNT(argc) char * const argv[]);
+LSX_API
+sox_effect_options(
+ LSX_PARAM_IN sox_effect_t *effp, /**< Effect pointer on which to set options. */
+ int argc, /**< Number of arguments in argv. */
+ LSX_PARAM_IN_COUNT(argc) char * const argv[] /**< Array of command-line options. */
+ );
-/* Effects chain */
+/**
+Client API:
+Returns an array containing the known effect handlers.
+@returns An array containing the known effect handlers.
+*/
+LSX_RETURN_VALID_Z LSX_RETURN_PURE
+sox_effect_fn_t const *
+LSX_API
+sox_get_effect_fns(void);
-/* Function that returns information about an effect handler */
-typedef const sox_effect_handler_t * (SOX_API *sox_effect_fn_t)(void);
-
-/* Returns an array containing the known effect handlers */
-LSX_RETURN_VALID_Z LSX_RETURN_PURE sox_effect_fn_t const *
-SOX_API sox_get_effect_fns(void);
-
+/**
+Client API:
+Deprecated macro that returns an array containing the known effect handlers.
+*/
#define sox_effect_fns (sox_get_effect_fns())
-/* Chain of effects to be applied to a stream */
-typedef struct sox_effects_chain_t {- sox_effect_t **effects; /* Table of effects to be applied to a stream */
- unsigned table_size; /* Number of entries in effects table */
- unsigned length; /* Number of effects to be applied */
- sox_sample_t **ibufc; /* Channel interleave buffer */
- sox_sample_t **obufc; /* Channel interleave buffer */
- sox_effects_globals_t global_info; /* Copy of global effects settings */
- sox_encodinginfo_t const * in_enc; /* Input encoding */
- sox_encodinginfo_t const * out_enc; /* Output encoding */
-} sox_effects_chain_t;
+/**
+Client API:
+Initializes an effects chain. Returned handle must be closed with sox_delete_effects_chain().
+@returns Handle, or null on failure.
+*/
+LSX_RETURN_OPT
+sox_effects_chain_t *
+LSX_API
+sox_create_effects_chain(
+ LSX_PARAM_IN sox_encodinginfo_t const * in_enc, /**< Input encoding. */
+ LSX_PARAM_IN sox_encodinginfo_t const * out_enc /**< Output encoding. */
+ );
-/* Initializes an effects chain. Returned handle must be closed with sox_delete_effects_chain(). */
-LSX_RETURN_OPT sox_effects_chain_t *
-SOX_API sox_create_effects_chain(
- LSX_PARAM_IN sox_encodinginfo_t const * in_enc,
- LSX_PARAM_IN sox_encodinginfo_t const * out_enc);
-
-/* Closes an effects chain. */
+/**
+Client API:
+Closes an effects chain.
+*/
void
-SOX_API sox_delete_effects_chain(
- LSX_PARAM_INOUT sox_effects_chain_t *ecp);
+LSX_API
+sox_delete_effects_chain(
+ LSX_PARAM_INOUT sox_effects_chain_t *ecp /**< Effects chain pointer. */
+ );
-/* Adds an effect to the effects chain, returns SOX_SUCCESS if successful. */
-int /* Returns SOX_SUCCESS if successful */
-SOX_API sox_add_effect(
- LSX_PARAM_INOUT sox_effects_chain_t * chain,
- LSX_PARAM_INOUT sox_effect_t * effp,
- LSX_PARAM_INOUT sox_signalinfo_t * in,
- LSX_PARAM_IN sox_signalinfo_t const * out);
+/**
+Client API:
+Adds an effect to the effects chain, returns SOX_SUCCESS if successful.
+@returns SOX_SUCCESS if successful.
+*/
+int
+LSX_API
+sox_add_effect(
+ LSX_PARAM_INOUT sox_effects_chain_t * chain, /**< Effects chain to which effect should be added . */
+ LSX_PARAM_INOUT sox_effect_t * effp, /**< Effect to be added. */
+ LSX_PARAM_INOUT sox_signalinfo_t * in, /**< Input format. */
+ LSX_PARAM_IN sox_signalinfo_t const * out /**< Output format. */
+ );
-/* Runs the effects chain, returns SOX_SUCCESS if successful. */
-int /* Returns SOX_SUCCESS if successful */
-SOX_API sox_flow_effects(
- LSX_PARAM_INOUT sox_effects_chain_t *,
- LSX_PARAM_IN int (SOX_API * callback)(sox_bool all_done, void * client_data),
- LSX_PARAM_IN_OPT void * client_data);
+/**
+Client API:
+Runs the effects chain, returns SOX_SUCCESS if successful.
+@returns SOX_SUCCESS if successful.
+*/
+int
+LSX_API
+sox_flow_effects(
+ LSX_PARAM_INOUT sox_effects_chain_t * chain, /**< Effects chain to run. */
+ LSX_PARAM_IN_OPT sox_flow_effects_callback callback, /**< Callback for monitoring flow progress. */
+ LSX_PARAM_IN_OPT void * client_data /**< Data to pass into callback. */
+ );
-/* Gets the number of clips that occurred while running an effects chain */
+/**
+Client API:
+Gets the number of clips that occurred while running an effects chain.
+@returns the number of clips that occurred while running an effects chain.
+*/
size_t
-SOX_API sox_effects_clips(
- LSX_PARAM_IN sox_effects_chain_t *);
+LSX_API
+sox_effects_clips(
+ LSX_PARAM_IN sox_effects_chain_t * chain /**< Effects chain from which to read clip information. */
+ );
-/* Shuts down an effect (calls stop on each of its flows) */
+/**
+Client API:
+Shuts down an effect (calls stop on each of its flows).
+@returns the number of clips from all flows.
+*/
size_t
-SOX_API sox_stop_effect(
- LSX_PARAM_INOUT_COUNT(effp->flows) sox_effect_t *effp);
+LSX_API
+sox_stop_effect(
+ LSX_PARAM_INOUT_COUNT(effp->flows) sox_effect_t * effp /**< Effect to stop. */
+ );
-/* Adds an already-initialized effect to the end of the chain */
+/**
+Client API:
+Adds an already-initialized effect to the end of the chain.
+*/
void
-SOX_API sox_push_effect_last(
- LSX_PARAM_INOUT sox_effects_chain_t *chain,
- LSX_PARAM_INOUT sox_effect_t *effp);
+LSX_API
+sox_push_effect_last(
+ LSX_PARAM_INOUT sox_effects_chain_t * chain, /**< Effects chain to which effect should be added. */
+ LSX_PARAM_INOUT sox_effect_t * effp /**< Effect to be added. */
+ );
-/* Removes and returns an effect from the end of the chain */
-LSX_RETURN_OPT sox_effect_t *
-SOX_API sox_pop_effect_last(
- LSX_PARAM_INOUT sox_effects_chain_t *chain);
+/**
+Client API:
+Removes and returns an effect from the end of the chain.
+@returns the removed effect, or null if no effects.
+*/
+LSX_RETURN_OPT
+sox_effect_t *
+LSX_API
+sox_pop_effect_last(
+ LSX_PARAM_INOUT sox_effects_chain_t *chain /**< Effects chain from which to remove an effect. */
+ );
-/* Shut down and delete an effect */
+/**
+Client API:
+Shut down and delete an effect.
+*/
void
-SOX_API sox_delete_effect(
- LSX_PARAM_INOUT_COUNT(effp->flows) sox_effect_t *effp);
+LSX_API
+sox_delete_effect(
+ LSX_PARAM_INOUT_COUNT(effp->flows) sox_effect_t *effp /**< Effect to be deleted. */
+ );
-/* Shut down and delete the last effect in the chain */
+/**
+Client API:
+Shut down and delete the last effect in the chain.
+*/
void
-SOX_API sox_delete_effect_last(
- LSX_PARAM_INOUT sox_effects_chain_t *chain);
+LSX_API
+sox_delete_effect_last(
+ LSX_PARAM_INOUT sox_effects_chain_t *chain /**< Effects chain from which to remove the last effect. */
+ );
-/* Shut down and delete all effects in the chain */
+/**
+Client API:
+Shut down and delete all effects in the chain.
+*/
void
-SOX_API sox_delete_effects(
- LSX_PARAM_INOUT sox_effects_chain_t *chain);
+LSX_API
+sox_delete_effects(
+ LSX_PARAM_INOUT sox_effects_chain_t *chain /**< Effects chain from which to delete effects. */
+ );
-/* The following routines are unique to the trim effect.
- * sox_trim_get_start can be used to find what is the start
- * of the trim operation as specified by the user.
- * sox_trim_clear_start will reset what ever the user specified
- * back to 0.
- * These two can be used together to find out what the user
- * wants to trim and use a sox_seek() operation instead. After
- * sox_seek()'ing, you should set the trim option to 0.
- */
+/**
+Client API:
+Gets the sample offset of the start of the trim, useful for efficiently
+skipping the part that will be trimmed anyway (get trim start, seek, then
+clear trim start).
+@returns the sample offset of the start of the trim.
+*/
sox_uint64_t
-SOX_API sox_trim_get_start(
- LSX_PARAM_IN sox_effect_t * effp);
+LSX_API
+sox_trim_get_start(
+ LSX_PARAM_IN sox_effect_t * effp /**< Trim effect. */
+ );
+
+/**
+Client API:
+Clears the start of the trim to 0.
+*/
void
-SOX_API sox_trim_clear_start(
- LSX_PARAM_INOUT sox_effect_t * effp);
+LSX_API
+sox_trim_clear_start(
+ LSX_PARAM_INOUT sox_effect_t * effp /**< Trim effect. */
+ );
+
+/**
+Client API:
+Gets the sample offset of the start of the crop, useful for efficiently
+skipping the part that will be trimmed anyway (get crop start, seek, then
+clear crop start).
+@returns the sample offset of the start of the crop.
+*/
sox_uint64_t
-SOX_API sox_crop_get_start(
- LSX_PARAM_IN sox_effect_t * effp);
+LSX_API
+sox_crop_get_start(
+ LSX_PARAM_IN sox_effect_t * effp /**< Crop effect. */
+ );
+
+/**
+Client API:
+Clears the start of the trim to 0.
+*/
void
-SOX_API sox_crop_clear_start(
- LSX_PARAM_INOUT sox_effect_t * effp);
+LSX_API
+sox_crop_clear_start(
+ LSX_PARAM_INOUT sox_effect_t * effp /**< Crop effect. */
+ );
-typedef int (SOX_API * sox_playlist_callback_t)(void * callback_data, LSX_PARAM_IN_Z char const * filename);
-
-/* Returns true if the specified file is a known playlist file type */
+/**
+Client API:
+Returns true if the specified file is a known playlist file type.
+@returns true if the specified file is a known playlist file type.
+*/
sox_bool
-SOX_API sox_is_playlist(
- LSX_PARAM_IN_Z char const * filename);
+LSX_API
+sox_is_playlist(
+ LSX_PARAM_IN_Z char const * filename /**< Name of file to examine. */
+ );
-/* Parses the specified playlist file */
-int /* Returns SOX_SUCCESS if successful */
-SOX_API sox_parse_playlist(
- LSX_PARAM_IN sox_playlist_callback_t callback,
- void * p,
- LSX_PARAM_IN char const * const listname);
+/**
+Client API:
+Parses the specified playlist file.
+@returns SOX_SUCCESS if successful.
+*/
+int
+LSX_API
+sox_parse_playlist(
+ LSX_PARAM_IN sox_playlist_callback_t callback, /**< Callback to call for each item in the playlist. */
+ void * p, /**< Data to pass to callback. */
+ LSX_PARAM_IN char const * const listname /**< Filename of playlist file. */
+ );
-/* Converts a SoX error code into an error string. */
-LSX_RETURN_VALID_Z LSX_RETURN_PURE char const *
-SOX_API sox_strerror(
- int sox_errno);
+/**
+Client API:
+Converts a SoX error code into an error string.
+@returns error string corresponding to the specified error code,
+or a generic message if the error code is not recognized.
+*/
+LSX_RETURN_VALID_Z LSX_RETURN_PURE
+char const *
+LSX_API
+sox_strerror(
+ int sox_errno /**< Error code to look up. */
+ );
-/* Gets the basename of the specified file, i.e. for "/a/b/c.d", gets "c".
- * Returns the number of characters written to base_buffer, excluding the null. */
+/**
+Client API:
+Gets the basename of the specified file; for example, the basename of
+"/a/b/c.d" would be "c".
+@returns the number of characters written to base_buffer, excluding the null,
+or 0 on failure.
+*/
size_t
-SOX_API sox_basename(
- LSX_PARAM_OUT_Z_CAP_POST_COUNT(base_buffer_len,return) char * base_buffer,
- size_t base_buffer_len,
- LSX_PARAM_IN_Z const char * filename);
+LSX_API
+sox_basename(
+ LSX_PARAM_OUT_Z_CAP_POST_COUNT(base_buffer_len,return) char * base_buffer, /**< Buffer into which basename should be written. */
+ size_t base_buffer_len, /**< Size of base_buffer, in bytes. */
+ LSX_PARAM_IN_Z char const * filename /**< Filename from which to extract basename. */
+ );
-/* WARNING BEGIN
- *
- * The items in this section are subject to instability. They only exist
- * in public API because sox (the application) make use of them but
- * may not be supported and may change rapidly.
- */
+/*****************************************************************************
+Internal API:
+WARNING - The items in this section are subject to instability. They only
+exist in the public header because sox (the application) currently uses them.
+These may be changed or removed in future versions of libSoX.
+*****************************************************************************/
+
+/**
+Plugins API:
+Print a fatal error in libSoX.
+*/
void
-SOX_API lsx_fail_impl(
- LSX_PARAM_IN_PRINTF const char *,
+LSX_API
+lsx_fail_impl(
+ LSX_PARAM_IN_PRINTF char const * fmt, /**< printf-style format string. */
...)
LSX_PRINTF12;
+
+/**
+Plugins API:
+Print a warning in libSoX.
+*/
void
-SOX_API lsx_warn_impl(
- LSX_PARAM_IN_PRINTF const char *,
+LSX_API
+lsx_warn_impl(
+ LSX_PARAM_IN_PRINTF char const * fmt, /**< printf-style format string. */
...)
LSX_PRINTF12;
+
+/**
+Plugins API:
+Print an informational message in libSoX.
+*/
void
-SOX_API lsx_report_impl(
- LSX_PARAM_IN_PRINTF const char *,
+LSX_API
+lsx_report_impl(
+ LSX_PARAM_IN_PRINTF char const * fmt, /**< printf-style format string. */
...)
LSX_PRINTF12;
+
+/**
+Plugins API:
+Print a debug message in libSoX.
+*/
void
-SOX_API lsx_debug_impl(
- LSX_PARAM_IN_PRINTF const char *,
+LSX_API
+lsx_debug_impl(
+ LSX_PARAM_IN_PRINTF char const * fmt, /**< printf-style format string. */
...)
LSX_PRINTF12;
+/**
+Plugins API:
+Report a fatal error in libSoX; printf-style arguments must follow.
+*/
#define lsx_fail sox_get_globals()->subsystem=__FILE__,lsx_fail_impl
+
+/**
+Plugins API:
+Report a warning in libSoX; printf-style arguments must follow.
+*/
#define lsx_warn sox_get_globals()->subsystem=__FILE__,lsx_warn_impl
+
+/**
+Plugins API:
+Report an informational message in libSoX; printf-style arguments must follow.
+*/
#define lsx_report sox_get_globals()->subsystem=__FILE__,lsx_report_impl
+
+/**
+Plugins API:
+Report a debug message in libSoX; printf-style arguments must follow.
+*/
#define lsx_debug sox_get_globals()->subsystem=__FILE__,lsx_debug_impl
+/**
+Plugins API:
+String name and integer values for enumerated types (type metadata), for use
+with LSX_ENUM_ITEM, lsx_find_enum_text, and lsx_find_enum_value.
+*/
typedef struct lsx_enum_item {- char const *text;
- unsigned value;
+ char const *text; /**< String name of enumeration. */
+ unsigned value; /**< Integer value of enumeration. */
} lsx_enum_item;
+
+/**
+Plugins API:
+Declares a static instance of an lsx_enum_item structure in format
+{ "item", prefixitem }, for use in declaring lsx_enum_item[] arrays.+@param prefix The prefix to prepend to the item in the enumeration symbolic name.
+@param item The user-visible text name of the item (must also be a valid C symbol name).
+*/
#define LSX_ENUM_ITEM(prefix, item) {#item, prefix##item},-LSX_RETURN_OPT LSX_RETURN_PURE lsx_enum_item const *
-SOX_API lsx_find_enum_text(
- LSX_PARAM_IN_Z char const * text,
- LSX_PARAM_IN lsx_enum_item const * lsx_enum_items,
- unsigned flags);
-#define LSX_FET_CASE 1
-LSX_RETURN_OPT LSX_RETURN_PURE lsx_enum_item const *
-SOX_API lsx_find_enum_value(
- unsigned value,
- LSX_PARAM_IN lsx_enum_item const * lsx_enum_items);
-LSX_RETURN_PURE int
-SOX_API lsx_enum_option(
- int c,
- LSX_PARAM_IN_Z char const * arg,
- LSX_PARAM_IN lsx_enum_item const * items);
-LSX_RETURN_PURE sox_bool
-SOX_API lsx_strends(
- LSX_PARAM_IN_Z char const * str,
- LSX_PARAM_IN_Z char const * end);
-LSX_RETURN_VALID_Z LSX_RETURN_PURE char const *
-SOX_API lsx_find_file_extension(
- LSX_PARAM_IN_Z char const * pathname);
-LSX_RETURN_VALID_Z char const *
-SOX_API lsx_sigfigs3(
- double number);
-LSX_RETURN_VALID_Z char const *
-SOX_API lsx_sigfigs3p(
- double percentage);
-LSX_RETURN_OPT void *
-SOX_API lsx_realloc(
- LSX_PARAM_IN_OPT void *ptr,
- size_t newsize);
-LSX_RETURN_PURE int
-SOX_API lsx_strcasecmp(
- LSX_PARAM_IN_Z const char * s1,
- LSX_PARAM_IN_Z const char * s2);
-LSX_RETURN_PURE int
-SOX_API lsx_strncasecmp(
- LSX_PARAM_IN_Z char const * s1,
- LSX_PARAM_IN_Z char const * s2,
- size_t n);
+/**
+Plugins API:
+Flags for use with lsx_find_enum_item.
+*/
+enum
+{+ lsx_find_enum_item_none = 0, /**< Default parameters (case-insensitive). */
+ lsx_find_enum_item_case_sensitive = 1 /**< Enable case-sensitive search. */
+};
+/**
+Plugins API:
+Looks up an enumeration by name in an array of lsx_enum_items.
+@returns the corresponding item, or null if not found.
+*/
+LSX_RETURN_OPT LSX_RETURN_PURE
+lsx_enum_item const *
+LSX_API
+lsx_find_enum_text(
+ LSX_PARAM_IN_Z char const * text, /**< Name of enumeration to find. */
+ LSX_PARAM_IN lsx_enum_item const * lsx_enum_items, /**< Array of items to search, with text == NULL for last item. */
+ int flags /**< Search flags: 0 (case-insensitive) or lsx_find_enum_item_case_sensitive (case-sensitive). */
+ );
+
+/**
+Plugins API:
+Looks up an enumeration by value in an array of lsx_enum_items.
+@returns the corresponding item, or null if not found.
+*/
+LSX_RETURN_OPT LSX_RETURN_PURE
+lsx_enum_item const *
+LSX_API
+lsx_find_enum_value(
+ unsigned value, /**< Enumeration value to find. */
+ LSX_PARAM_IN lsx_enum_item const * lsx_enum_items /**< Array of items to search, with text == NULL for last item. */
+ );
+
+/**
+Plugins API:
+Looks up a command-line argument in a set of enumeration names, showing an
+error message if the argument is not found in the set of names.
+@returns The enumeration value corresponding to the matching enumeration, or
+INT_MAX if the argument does not match any enumeration name.
+*/
+LSX_RETURN_PURE
+int
+LSX_API
+lsx_enum_option(
+ int c, /**< Option character to which arg is associated, for example with -a, c would be 'a'. */
+ LSX_PARAM_IN_Z char const * arg, /**< Argument to find in enumeration list. */
+ LSX_PARAM_IN lsx_enum_item const * items /**< Array of items to search, with text == NULL for last item. */
+ );
+
+/**
+Plugins API:
+Determines whether the specified string ends with the specified suffix (case-sensitive).
+@returns true if the specified string ends with the specified suffix.
+*/
+LSX_RETURN_PURE
+sox_bool
+LSX_API
+lsx_strends(
+ LSX_PARAM_IN_Z char const * str, /**< String to search. */
+ LSX_PARAM_IN_Z char const * end /**< Suffix to search for. */
+ );
+
+/**
+Plugins API:
+Finds the file extension for a filename.
+@returns the file extension, not including the '.', or null if filename does
+not have an extension.
+*/
+LSX_RETURN_VALID_Z LSX_RETURN_PURE
+char const *
+LSX_API
+lsx_find_file_extension(
+ LSX_PARAM_IN_Z char const * pathname /**< Filename to search for extension. */
+ );
+
+/**
+Plugins API:
+Formats the specified number with up to three significant figures and adds a
+metric suffix in place of the exponent, such as 1.23G.
+@returns A static buffer with the formatted number, valid until the next time
+this function is called (note: not thread safe).
+*/
+LSX_RETURN_VALID_Z
+char const *
+LSX_API
+lsx_sigfigs3(
+ double number /**< Number to be formatted. */
+ );
+
+/**
+Plugins API:
+Formats the specified number as a percentage, showing up to three significant
+figures.
+@returns A static buffer with the formatted number, valid until the next time
+this function is called (note: not thread safe).
+*/
+LSX_RETURN_VALID_Z
+char const *
+LSX_API
+lsx_sigfigs3p(
+ double percentage /**< Number to be formatted. */
+ );
+
+/**
+Plugins API:
+Allocates, deallocates, or resizes; like C's realloc, except that this version
+terminates the running application if unable to allocate the requested memory.
+@returns New buffer, or null if buffer was freed.
+*/
+LSX_RETURN_OPT
+void *
+LSX_API
+lsx_realloc(
+ LSX_PARAM_IN_OPT void *ptr, /**< Pointer to be freed or resized, or null if allocating a new buffer. */
+ size_t newsize /**< New size for buffer, or 0 to free the buffer. */
+ );
+
+/**
+Plugins API:
+Like strcmp, except that the characters are compared without regard to case.
+@returns 0 (s1 == s2), negative (s1 < s2), or positive (s1 > s2).
+*/
+LSX_RETURN_PURE
+int
+LSX_API
+lsx_strcasecmp(
+ LSX_PARAM_IN_Z char const * s1, /**< First string. */
+ LSX_PARAM_IN_Z char const * s2 /**< Second string. */
+ );
+
+
+/**
+Plugins API:
+Like strncmp, except that the characters are compared without regard to case.
+@returns 0 (s1 == s2), negative (s1 < s2), or positive (s1 > s2).
+*/
+LSX_RETURN_PURE
+int
+LSX_API
+lsx_strncasecmp(
+ LSX_PARAM_IN_Z char const * s1, /**< First string. */
+ LSX_PARAM_IN_Z char const * s2, /**< Second string. */
+ size_t n /**< Maximum number of characters to examine. */
+ );
+
+/**
+Plugins API:
+Is option argument unsupported, required, or optional.
+*/
typedef enum lsx_option_arg_t {- lsx_option_arg_none,
- lsx_option_arg_required,
- lsx_option_arg_optional
+ lsx_option_arg_none, /**< Option does not have an argument. */
+ lsx_option_arg_required, /**< Option requires an argument. */
+ lsx_option_arg_optional /**< Option can optionally be followed by an argument. */
} lsx_option_arg_t;
-typedef struct lsx_option_t {- char const * name;
- lsx_option_arg_t has_arg;
- int * flag;
- int val;
-} lsx_option_t;
-
+/**
+Plugins API:
+lsx_getopt_init options.
+*/
typedef enum lsx_getopt_flags_t {- lsx_getopt_flag_none = 0, /* no flags (no output, not long-only) */
- lsx_getopt_flag_opterr = 1, /* if set, invalid options trigger lsx_warn output */
- lsx_getopt_flag_longonly = 2 /* if set, recognize accept -option as a long option */
+ lsx_getopt_flag_none = 0, /**< no flags (no output, not long-only) */
+ lsx_getopt_flag_opterr = 1, /**< if set, invalid options trigger lsx_warn output */
+ lsx_getopt_flag_longonly = 2 /**< if set, recognize -option as a long option */
} lsx_getopt_flags_t;
+/**
+Plugins API:
+lsx_getopt long option descriptor.
+*/
+typedef struct lsx_option_t {+ char const * name; /**< Name of the long option. */
+ lsx_option_arg_t has_arg; /**< Whether the long option supports an argument and, if so, whether the argument is required or optional. */
+ int * flag; /**< Flag to set if argument is present. */
+ int val; /**< Value to put in flag if argument is present. */
+} lsx_option_t;
+
+/**
+Plugins API:
+lsx_getopt session information (initialization data and state).
+*/
typedef struct lsx_getopt_t {- int argc; /* IN argc: Number of arguments in argv */
- char * const * argv; /* IN argv: Array of arguments */
- char const * shortopts;/* IN shortopts: Short option characters */
- lsx_option_t const * longopts; /* IN longopts: Array of long option descriptors */
- lsx_getopt_flags_t flags; /* IN flags: Flags for longonly and opterr */
- char const * curpos; /* INOUT curpos: Maintains state between calls to lsx_getopt */
- int ind; /* INOUT optind: Maintains the index of next element to be processed */
- int opt; /* OUT optopt: Receives the option character that caused error */
- char const * arg; /* OUT optarg: Receives the value of the option's argument */
- int lngind; /* OUT lngind: Receives the index of the matched long option or -1 if not a long option */
+ int argc; /**< IN argc: Number of arguments in argv */
+ char * const * argv; /**< IN argv: Array of arguments */
+ char const * shortopts;/**< IN shortopts: Short option characters */
+ lsx_option_t const * longopts; /**< IN longopts: Array of long option descriptors */
+ lsx_getopt_flags_t flags; /**< IN flags: Flags for longonly and opterr */
+ char const * curpos; /**< INOUT curpos: Maintains state between calls to lsx_getopt */
+ int ind; /**< INOUT optind: Maintains the index of next element to be processed */
+ int opt; /**< OUT optopt: Receives the option character that caused error */
+ char const * arg; /**< OUT optarg: Receives the value of the option's argument */
+ int lngind; /**< OUT lngind: Receives the index of the matched long option or -1 if not a long option */
} lsx_getopt_t;
-/* Initializes an lsx_getopt_t structure for use with lsx_getopt. */
+/**
+Plugins API:
+Initializes an lsx_getopt_t structure for use with lsx_getopt.
+*/
void
-SOX_API lsx_getopt_init(
- LSX_PARAM_IN int argc, /* Number of arguments in argv */
- LSX_PARAM_IN_COUNT(argc) char * const * argv, /* Array of arguments */
- LSX_PARAM_IN_Z char const * shortopts, /* Short options, i.e. ":abc:def::ghi" (+/- not supported) */
- LSX_PARAM_IN_OPT lsx_option_t const * longopts, /* Array of long option descriptors */
- LSX_PARAM_IN lsx_getopt_flags_t flags, /* Flags for longonly and opterr */
- LSX_PARAM_IN int first, /* First argv to check (usually 1) */
- LSX_PARAM_OUT lsx_getopt_t * state); /* State object to be initialized */
+LSX_API
+lsx_getopt_init(
+ LSX_PARAM_IN int argc, /**< Number of arguments in argv */
+ LSX_PARAM_IN_COUNT(argc) char * const * argv, /**< Array of arguments */
+ LSX_PARAM_IN_Z char const * shortopts, /**< Short options, for example ":abc:def::ghi" (+/- not supported) */
+ LSX_PARAM_IN_OPT lsx_option_t const * longopts, /**< Array of long option descriptors */
+ LSX_PARAM_IN lsx_getopt_flags_t flags, /**< Flags for longonly and opterr */
+ LSX_PARAM_IN int first, /**< First argv to check (usually 1) */
+ LSX_PARAM_OUT lsx_getopt_t * state /**< State object to be initialized */
+ );
-/* Gets the next option. Options are parameters that start with "-" or "--".
- * If no more options, returns -1. If unrecognized short option, returns '?'.
- * If a recognized short option is missing a required argument,
- * return (shortopts[0]==':' ? ':' : '?'). If successfully recognized short
- * option, return the recognized character. If successfully recognized long
- * option, returns (option.flag ? 0 : option.val).
- * Note: lsx_getopt does not permute the non-option arguments. */
-int /* Returns option character (short), val or 0 (long), or -1 (no more) */
-SOX_API lsx_getopt(
- LSX_PARAM_INOUT lsx_getopt_t * state);
+/**
+Plugins API:
+Gets the next option. Options are parameters that start with "-" or "--".
+If no more options, returns -1. If unrecognized short option, returns '?'.
+If a recognized short option is missing a required argument,
+return (shortopts[0]==':' ? ':' : '?'). If successfully recognized short
+option, return the recognized character. If successfully recognized long
+option, returns (option.flag ? 0 : option.val).
+Note: lsx_getopt does not permute the non-option arguments.
+@returns option character (short), val or 0 (long), or -1 (no more).
+*/
+int
+LSX_API
+lsx_getopt(
+ LSX_PARAM_INOUT lsx_getopt_t * state /**< The getopt state pointer. */
+ );
/* WARNING END */
--- a/src/synth.c
+++ b/src/synth.c
@@ -321,7 +321,7 @@
}
while (argn < argc) { /* type [combine] [f1[-f2] [off [ph [p1 [p2 [p3]]]]]] */- lsx_enum_item const * enum_p = lsx_find_enum_text(argv[argn], synth_type, LSX_FET_CASE);
+ lsx_enum_item const * enum_p = lsx_find_enum_text(argv[argn], synth_type, lsx_find_enum_item_case_sensitive);
if (enum_p == NULL) { lsx_fail("no type given");@@ -335,7 +335,7 @@
break;
/* maybe there is a combine-type in next arg */
- enum_p = lsx_find_enum_text(argv[argn], combine_type, LSX_FET_CASE);
+ enum_p = lsx_find_enum_text(argv[argn], combine_type, lsx_find_enum_item_case_sensitive);
if (enum_p != NULL) {chan->combine = enum_p->value;
if (++argn == argc)
@@ -343,7 +343,7 @@
}
/* read frequencies if given */
- if (!lsx_find_enum_text(argv[argn], synth_type, LSX_FET_CASE) &&
+ if (!lsx_find_enum_text(argv[argn], synth_type, lsx_find_enum_item_case_sensitive) &&
argv[argn][0] != '-') {static const char sweeps[] = ":+/-";
--- a/src/util.c
+++ b/src/util.c
@@ -67,10 +67,10 @@
return result;
}
-lsx_enum_item const * lsx_find_enum_text(char const * text, lsx_enum_item const * enum_items, unsigned flags)
+lsx_enum_item const * lsx_find_enum_text(char const * text, lsx_enum_item const * enum_items, int flags)
{lsx_enum_item const * result = NULL; /* Assume not found */
- sox_bool sensitive = !!(flags & LSX_FET_CASE);
+ sox_bool sensitive = !!(flags & lsx_find_enum_item_case_sensitive);
while (enum_items->text) {if ((!sensitive && !strcasecmp(text, enum_items->text)) ||