openharmony/third_party_libsnd
1
0
Fork 0
mirror of https://gitee.com/openharmony/third_party_libsnd synced 2025-02-10 21:02:49 +00:00
Code Issues Actions 1 Packages Projects Releases Wiki Activity

doc: Add information about MPEG support

Browse Source
This commit is contained in:
evpobr 2021-03-26 12:10:48 +05:00
parent f97fa5e6ba
commit 72521cf4f7
5 changed files with 161 additions and 71 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

21
CHANGELOG.md
View File

@ -9,6 +9,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
### Added
* MPEG Encode/Decode Support.
Uses libmpg123 for decode, liblame for encode. Encoding and decoding support
is independent of each other and is split into separate files. MPEG support
is generalized as subformats, `SF_FORMAT_MPEG_LAYER`(I,II,III) so that it
might be used by other containers (`MPEG1WAVEFORMAT` for example), but also
contains a major format `SF_FORMAT_MPEG` for 'mp3 files.'
Encoding Status:
* Layer III encoding
* ID3v1 writing
* ID3v2 writing
* Lame/Xing Tag writing
* Bitrate selection command
* VBR or CBR
Decoding Status:
* Layers I/II/III decoding
* ID3v1 reading
* ID3v2 reading
* Seeking
* This `CHANGELOG.md`. All notable changes to this project will be documented in
this file. The old `NEWS` file has been renamed to `NEWS.OLD` and is no longer
updated.

6
docs/FAQ.md
View File

@ -438,10 +438,12 @@ Use CMake project.
## Q20 : Why doesn't libsndfile support MP3? {#Q020}
In the past, MP3 was not supported because the technology behind MP3 was
~~In the past, MP3 was not supported because the technology behind MP3 was
patented. Those patents have now expired and there is an
[open ticket](https://github.com/libsndfile/libsndfile/issues/258) to implement
MP3 support.
MP3 support.~~
**Update :** Starting from version 1.1.0 libsndfile supports MP3 format.
## Q21 : How do I use libsndfile in a closed source or commercial program and comply with the license? {#Q021}

140
docs/api.md
View File

@ -112,74 +112,78 @@ value. The currently understood formats are listed in *sndfile.h* as follows and
also include bitmasks for separating major and minor file types. Not all
combinations of endian-ness and major and minor file types are valid.
| Name | Value | Description |
|:-----------------------|:-----------|:-------------------------------------------|
| **Major formats.** |
| SF_FORMAT_WAV | 0x010000 | Microsoft WAV format (little endian). |
| SF_FORMAT_AIFF | 0x020000 | Apple/SGI AIFF format (big endian). |
| SF_FORMAT_AU | 0x030000 | Sun/NeXT AU format (big endian). |
| SF_FORMAT_RAW | 0x040000 | RAW PCM data. |
| SF_FORMAT_PAF | 0x050000 | Ensoniq PARIS file format. |
| SF_FORMAT_SVX | 0x060000 | Amiga IFF / SVX8 / SV16 format. |
| SF_FORMAT_NIST | 0x070000 | Sphere NIST format. |
| SF_FORMAT_VOC | 0x080000 | VOC files. |
| SF_FORMAT_IRCAM | 0x0A0000 | Berkeley/IRCAM/CARL |
| SF_FORMAT_W64 | 0x0B0000 | Sonic Foundry's 64 bit RIFF/WAV |
| SF_FORMAT_MAT4 | 0x0C0000 | Matlab (tm) V4.2 / GNU Octave 2.0 |
| SF_FORMAT_MAT5 | 0x0D0000 | Matlab (tm) V5.0 / GNU Octave 2.1 |
| SF_FORMAT_PVF | 0x0E0000 | Portable Voice Format |
| SF_FORMAT_XI | 0x0F0000 | Fasttracker 2 Extended Instrument |
| SF_FORMAT_HTK | 0x100000 | HMM Tool Kit format |
| SF_FORMAT_SDS | 0x110000 | Midi Sample Dump Standard |
| SF_FORMAT_AVR | 0x120000 | Audio Visual Research |
| SF_FORMAT_WAVEX | 0x130000 | MS WAVE with WAVEFORMATEX |
| SF_FORMAT_SD2 | 0x160000 | Sound Designer 2 |
| SF_FORMAT_FLAC | 0x170000 | FLAC lossless file format |
| SF_FORMAT_CAF | 0x180000 | Core Audio File format |
| SF_FORMAT_WVE | 0x190000 | Psion WVE format |
| SF_FORMAT_OGG | 0x200000 | Xiph OGG container |
| SF_FORMAT_MPC2K | 0x210000 | Akai MPC 2000 sampler |
| SF_FORMAT_RF64 | 0x220000 | RF64 WAV file |
| **Subtypes.** |
| SF_FORMAT_PCM_S8 | 0x0001 | Signed 8 bit data |
| SF_FORMAT_PCM_16 | 0x0002 | Signed 16 bit data |
| SF_FORMAT_PCM_24 | 0x0003 | Signed 24 bit data |
| SF_FORMAT_PCM_32 | 0x0004 | Signed 32 bit data |
| SF_FORMAT_PCM_U8 | 0x0005 | Unsigned 8 bit data (WAV and RAW only) |
| SF_FORMAT_FLOAT | 0x0006 | 32 bit float data |
| SF_FORMAT_DOUBLE | 0x0007 | 64 bit float data |
| SF_FORMAT_ULAW | 0x0010 | U-Law encoded. |
| SF_FORMAT_ALAW | 0x0011 | A-Law encoded. |
| SF_FORMAT_IMA_ADPCM | 0x0012 | IMA ADPCM. |
| SF_FORMAT_MS_ADPCM | 0x0013 | Microsoft ADPCM. |
| SF_FORMAT_GSM610 | 0x0020 | GSM 6.10 encoding. |
| SF_FORMAT_VOX_ADPCM | 0x0021 | OKI / Dialogix ADPCM |
| SF_FORMAT_NMS_ADPCM_16 | 0x0022 | 16kbs NMS G721-variant encoding. |
| SF_FORMAT_NMS_ADPCM_24 | 0x0023 | 24kbs NMS G721-variant encoding. |
| SF_FORMAT_NMS_ADPCM_32 | 0x0024 | 32kbs NMS G721-variant encoding. |
| SF_FORMAT_G721_32 | 0x0030 | 32kbs G721 ADPCM encoding. |
| SF_FORMAT_G723_24 | 0x0031 | 24kbs G723 ADPCM encoding. |
| SF_FORMAT_G723_40 | 0x0032 | 40kbs G723 ADPCM encoding. |
| SF_FORMAT_DWVW_12 | 0x0040 | 12 bit Delta Width Variable Word encoding. |
| SF_FORMAT_DWVW_16 | 0x0041 | 16 bit Delta Width Variable Word encoding. |
| SF_FORMAT_DWVW_24 | 0x0042 | 24 bit Delta Width Variable Word encoding. |
| SF_FORMAT_DWVW_N | 0x0043 | N bit Delta Width Variable Word encoding. |
| SF_FORMAT_DPCM_8 | 0x0050 | 8 bit differential PCM (XI only) |
| SF_FORMAT_DPCM_16 | 0x0051 | 16 bit differential PCM (XI only) |
| SF_FORMAT_VORBIS | 0x0060 | Xiph Vorbis encoding. |
| SF_FORMAT_OPUS | 0x0064 | Xiph/Skype Opus encoding. |
| SF_FORMAT_ALAC_16 | 0x0070 | Apple Lossless Audio Codec (16 bit). |
| SF_FORMAT_ALAC_20 | 0x0071 | Apple Lossless Audio Codec (20 bit). |
| SF_FORMAT_ALAC_24 | 0x0072 | Apple Lossless Audio Codec (24 bit). |
| SF_FORMAT_ALAC_32 | 0x0073 | Apple Lossless Audio Codec (32 bit). |
| **Endian-ness options.** |
| SF_ENDIAN_FILE | 0x00000000 | Default file endian-ness. |
| SF_ENDIAN_LITTLE | 0x10000000 | Force little endian-ness. |
| SF_ENDIAN_BIG | 0x20000000 | Force big endian-ness. |
| SF_ENDIAN_CPU | 0x30000000 | Force CPU endian-ness. |
| SF_FORMAT_SUBMASK | 0x0000FFFF | |
| SF_FORMAT_TYPEMASK | 0x0FFF0000 | |
| SF_FORMAT_ENDMASK | 0x30000000 | |
| Name | Value | Description |
|:-------------------------|:-----------|:-------------------------------------------|
| **Major formats.** |
| SF_FORMAT_WAV | 0x010000 | Microsoft WAV format (little endian). |
| SF_FORMAT_AIFF | 0x020000 | Apple/SGI AIFF format (big endian). |
| SF_FORMAT_AU | 0x030000 | Sun/NeXT AU format (big endian). |
| SF_FORMAT_RAW | 0x040000 | RAW PCM data. |
| SF_FORMAT_PAF | 0x050000 | Ensoniq PARIS file format. |
| SF_FORMAT_SVX | 0x060000 | Amiga IFF / SVX8 / SV16 format. |
| SF_FORMAT_NIST | 0x070000 | Sphere NIST format. |
| SF_FORMAT_VOC | 0x080000 | VOC files. |
| SF_FORMAT_IRCAM | 0x0A0000 | Berkeley/IRCAM/CARL |
| SF_FORMAT_W64 | 0x0B0000 | Sonic Foundry's 64 bit RIFF/WAV |
| SF_FORMAT_MAT4 | 0x0C0000 | Matlab (tm) V4.2 / GNU Octave 2.0 |
| SF_FORMAT_MAT5 | 0x0D0000 | Matlab (tm) V5.0 / GNU Octave 2.1 |
| SF_FORMAT_PVF | 0x0E0000 | Portable Voice Format |
| SF_FORMAT_XI | 0x0F0000 | Fasttracker 2 Extended Instrument |
| SF_FORMAT_HTK | 0x100000 | HMM Tool Kit format |
| SF_FORMAT_SDS | 0x110000 | Midi Sample Dump Standard |
| SF_FORMAT_AVR | 0x120000 | Audio Visual Research |
| SF_FORMAT_WAVEX | 0x130000 | MS WAVE with WAVEFORMATEX |
| SF_FORMAT_SD2 | 0x160000 | Sound Designer 2 |
| SF_FORMAT_FLAC | 0x170000 | FLAC lossless file format |
| SF_FORMAT_CAF | 0x180000 | Core Audio File format |
| SF_FORMAT_WVE | 0x190000 | Psion WVE format |
| SF_FORMAT_OGG | 0x200000 | Xiph OGG container |
| SF_FORMAT_MPC2K | 0x210000 | Akai MPC 2000 sampler |
| SF_FORMAT_RF64 | 0x220000 | RF64 WAV file |
| SF_FORMAT_MPEG | 0x230000 | MPEG-1/2 audio stream |
| **Subtypes.** |
| SF_FORMAT_PCM_S8 | 0x0001 | Signed 8 bit data |
| SF_FORMAT_PCM_16 | 0x0002 | Signed 16 bit data |
| SF_FORMAT_PCM_24 | 0x0003 | Signed 24 bit data |
| SF_FORMAT_PCM_32 | 0x0004 | Signed 32 bit data |
| SF_FORMAT_PCM_U8 | 0x0005 | Unsigned 8 bit data (WAV and RAW only) |
| SF_FORMAT_FLOAT | 0x0006 | 32 bit float data |
| SF_FORMAT_DOUBLE | 0x0007 | 64 bit float data |
| SF_FORMAT_ULAW | 0x0010 | U-Law encoded. |
| SF_FORMAT_ALAW | 0x0011 | A-Law encoded. |
| SF_FORMAT_IMA_ADPCM | 0x0012 | IMA ADPCM. |
| SF_FORMAT_MS_ADPCM | 0x0013 | Microsoft ADPCM. |
| SF_FORMAT_GSM610 | 0x0020 | GSM 6.10 encoding. |
| SF_FORMAT_VOX_ADPCM | 0x0021 | OKI / Dialogix ADPCM |
| SF_FORMAT_NMS_ADPCM_16 | 0x0022 | 16kbs NMS G721-variant encoding. |
| SF_FORMAT_NMS_ADPCM_24 | 0x0023 | 24kbs NMS G721-variant encoding. |
| SF_FORMAT_NMS_ADPCM_32 | 0x0024 | 32kbs NMS G721-variant encoding. |
| SF_FORMAT_G721_32 | 0x0030 | 32kbs G721 ADPCM encoding. |
| SF_FORMAT_G723_24 | 0x0031 | 24kbs G723 ADPCM encoding. |
| SF_FORMAT_G723_40 | 0x0032 | 40kbs G723 ADPCM encoding. |
| SF_FORMAT_DWVW_12 | 0x0040 | 12 bit Delta Width Variable Word encoding. |
| SF_FORMAT_DWVW_16 | 0x0041 | 16 bit Delta Width Variable Word encoding. |
| SF_FORMAT_DWVW_24 | 0x0042 | 24 bit Delta Width Variable Word encoding. |
| SF_FORMAT_DWVW_N | 0x0043 | N bit Delta Width Variable Word encoding. |
| SF_FORMAT_DPCM_8 | 0x0050 | 8 bit differential PCM (XI only) |
| SF_FORMAT_DPCM_16 | 0x0051 | 16 bit differential PCM (XI only) |
| SF_FORMAT_VORBIS | 0x0060 | Xiph Vorbis encoding. |
| SF_FORMAT_OPUS | 0x0064 | Xiph/Skype Opus encoding. |
| SF_FORMAT_ALAC_16 | 0x0070 | Apple Lossless Audio Codec (16 bit). |
| SF_FORMAT_ALAC_20 | 0x0071 | Apple Lossless Audio Codec (20 bit). |
| SF_FORMAT_ALAC_24 | 0x0072 | Apple Lossless Audio Codec (24 bit). |
| SF_FORMAT_ALAC_32 | 0x0073 | Apple Lossless Audio Codec (32 bit). |
| SF_FORMAT_MPEG_LAYER_I | 0x0080 | MPEG-1 Audio Layer I. |
| SF_FORMAT_MPEG_LAYER_II | 0x0081 | MPEG-1 Audio Layer II. |
| SF_FORMAT_MPEG_LAYER_III | 0x0082 | MPEG-2 Audio Layer III. |
| **Endian-ness options.** |
| SF_ENDIAN_FILE | 0x00000000 | Default file endian-ness. |
| SF_ENDIAN_LITTLE | 0x10000000 | Force little endian-ness. |
| SF_ENDIAN_BIG | 0x20000000 | Force big endian-ness. |
| SF_ENDIAN_CPU | 0x30000000 | Force CPU endian-ness. |
| SF_FORMAT_SUBMASK | 0x0000FFFF | |
| SF_FORMAT_TYPEMASK | 0x0FFF0000 | |
| SF_FORMAT_ENDMASK | 0x30000000 | |
Every call to **sf_open**() should be matched with a call to
[**sf_close**()](#close) to free up memory allocated during the call to **sf_open**().

62
docs/command.md
View File

@ -81,6 +81,8 @@ The available commands are as follows:
| [SFC_RF64_AUTO_DOWNGRADE](#sfc_rf64_auto_downgrade) | Set auto downgrade from RF64 to WAV. |
| [SFC_GET_ORIGINAL_SAMPLERATE](#sfc_get_original_samplerate) | Get original samplerate metadata. |
| [SFC_SET_ORIGINAL_SAMPLERATE](#sfc_set_original_samplerate) | Set original samplerate metadata. |
| [SFC_GET_BITRATE_MODE](#sfc_get_bitrate_mode) | Get bitrate mode.
| [SFC_SET_BITRATE_MODE](#sfc_set_bitrate_mode) | Set bitrate mode.
---
@ -1927,3 +1929,63 @@ Returns SF_TRUE on success, SF_FALSE otherwise.
On write, can only succeed if no data has been written. On read, if successful,
[SFC_GET_CURRENT_SF_INFO](#sfc_get_current_sf_info) should be called to
determine the new frames count and samplerate
## SFC_GET_BITRATE_MODE
Get bitrate mode.
The bitrate mode is one of:
| Name | Value | Description |
|:-------------------------|:------|:------------------|
| SF_BITRATE_MODE_CONSTANT | 800 | Constant bitrate. |
| SF_BITRATE_MODE_AVERAGE | 801 | Average bitrate. |
| SF_BITRATE_MODE_VARIABLE | 802 | Variable bitrate. |
### Parameters
sndfile
: A valid SNDFILE* pointer
cmd
: SFC_GET_BITRATE_MODE
data
: NULL
datasize
: anything
### Return value
Returns one of `SF_BITRATE_MODE_XXX` on success, `-1` otherwise.
## SFC_SET_BITRATE_MODE
Set bitrate mode.
The bitrate mode is one of:
| Name | Value | Description |
|:-------------------------|:------|:------------------|
| SF_BITRATE_MODE_CONSTANT | 800 | Constant bitrate. |
| SF_BITRATE_MODE_AVERAGE | 801 | Average bitrate. |
| SF_BITRATE_MODE_VARIABLE | 802 | Variable bitrate. |
### Parameters
sndfile
: A valid SNDFILE* pointer
cmd
: SFC_SET_BITRATE_MODE
data
: pointer to an integer
datasize
: sizeof (int)
### Return value
Returns `SF_TRUE` on success, `SF_FALSE` otherwise.

3
docs/formats.md
View File

@ -40,11 +40,12 @@ From version 1.0.18, libsndfile also reads and writes
From version 1.0.29, libsndfile can read and write
[Ogg/Opus](https://opus-codec.org/).
From version 1.1.0, libsndfile can read and write MP3.
Some of the file formats I am also interested in adding are:
- Kurzweil K2000 sampler files.
- Ogg Speex.
- MPEG Layer 3 (commonly known as MP3)
Other file formats may also be added on request.