Libcwav 3DS: Difference between revisions

Libcwav
Libcwav
General
Author	PabloMK7 (mariohackandglitch)
Type	Media Players
Version	1.0
License	Mixed
Last Updated	2021/01/27
Links
	Download
	Website
	Source

Latest revision as of 06:26, 6 May 2024

libcwav is a library for playing (b)cwav files on the 3DS.

The goal of this library is to provide an interface for playing (b)cwav files in 3DS homebrew sofware. The way it is designed allows to play these files in non-application environments, such as 3GX game plugins or applets, as it provides support for the CSND system service. Unlike (b)cstm files which are streamed in chunks from their storage media, (b)cwav files are fully loaded into the linear RAM. Therefore, (b)cwav files are only meant for small sound effects. This library provides support for the ADPCM encodings, which heavily reduce the required memory to play the file.

Building

Make sure you have devkitpro installed and working.

Clone or download the repo and open a command prompt. Run make install and confirm there aren't any errors.
In your project makefile, add the following to the LIBDIRS line (or similar): $(DEVKITPRO)/libcwav
In your project makefile, add the following to the LIBS line (or similar): -lcwav if the already listed libraries start with -l or just cwav if they don't.
Add #include "cwav.h" and/or #include "cwav_file.h" in your source files to use the library.

You can check all the available function calls in the documentation provided in .h|cwav.h and cwav_file.h. Also, you can see an example application in example_libcwav.

User guide

CWAV Audio Encodings

The following audio encodings are supported.

PCM8/PCM16 - Uncompressed 8/16 bit PCM. Useful if memory usage is not a problem.
DSP ADPCM - Lossy compression format, useful if the available memory is limited. Can only be played with DSP.
IMA ADPCM - Lossy compression format, similar to DSP ADPCM. Can only be played with CSND.

System Services

The following system services used to play the audio are supported.

DSP - This system service is used by normal applications. It is recommended to use this system service, as it properly supports suspending applications and sleep mode.
CSND - This system service is used by applets to play audio. It has the advantage of playing audio on top of running/suspended applications, whitout causing any interferences.
- Use this system service if you want to play audio in applets or 3GX game plugins.
- Make sure to use cwavDoAptHook() or cwavNotifyAptEvent() to handle apt events (app suspend, sleep or exit).

Create (b)cwav files

You can use cwavtool to create (b)cwav files from other audio formats. It supports all possible encodings and loop points.

Changelog

v1.0 2021/01/27

Initial release.

Credits

libctru - CSND and DSP implementation.
3dbrew.org - (b)cwav file specification.

@@ Line 1: / Line 1: @@
-{{Infobox 3DS homebrew
+{{Infobox 3DS Homebrews
-| title = Libcwav
+|title=Libcwav
-| image = https://dlhb.gamebrew.org/3dshomebrew/Libcwav.jpg|250px
+|image=Libcwav2.png
-| type = Media players
+|description=A 3DS library to play BCWAV files.
-| version = v1.0
+|author=PabloMK7 (mariohackandglitch)
-| licence = Mixed
+|lastupdated=2021/01/27
-| author = mariohackandglitch
+|type=Media Players
-| website = https://github.com/mariohackandglitch/libcwav
+|version=1.0
-| download = https://dlhb.gamebrew.org/3dshomebrew/Libcwav.rar
+|license=Mixed
-| source = https://dlhb.gamebrew.org/3dshomebrew/Libcwav.rar
+|download=https://dlhb.gamebrew.org/3dshomebrews/libcwav.7z
+|website=https://github.com/mariohackandglitch/libcwav
+|source=https://github.com/mariohackandglitch/libcwav
 }}
-<youtube>oQsZ_MCmht4</youtube>
+libcwav is a library for playing (b)cwav files on the 3DS.
-= libcwav =
+The goal of this library is to provide an interface for playing (b)cwav files in 3DS homebrew sofware. The way it is designed allows to play these files in non-application environments, such as 3GX game plugins or applets, as it provides support for the CSND system service. Unlike (b)cstm files which are streamed in chunks from their storage media, (b)cwav files are fully loaded into the linear RAM. Therefore, (b)cwav files are only meant for small sound effects. This library provides support for the ADPCM encodings, which heavily reduce the required memory to play the file.
-A library for playing '''(b)cwav''' files on the '''3DS'''.
+==Building==
+Make sure you have [https://devkitpro.org/wiki/Getting_Started devkitpro] installed and working.
+* Clone or download the repo and open a command prompt. Run <code>make install</code> and confirm there aren't any errors.
+* In your project makefile, add the following to the <code>LIBDIRS</code> line (or similar): <code>$(DEVKITPRO)/libcwav</code>
+* In your project makefile, add the following to the <code>LIBS</code> line (or similar): <code>-lcwav</code> if the already listed libraries start with <code>-l</code> or just <code>cwav</code> if they don't.
+* Add <code>#include &quot;cwav.h&quot;</code> and/or <code>#include &quot;cwav_file.h&quot;</code> in your source files to use the library.
-= Description =
+You can check all the available function calls in the documentation provided in [https://github.com/mariohackandglitch/libcwav/blob/main/include/cwav.h .h|cwav.h] and [https://github.com/mariohackandglitch/libcwav/blob/main/include/cwav_file.h cwav_file.h]. Also, you can see an example application in [https://github.com/mariohackandglitch/libcwav/blob/main/example_libcwav example_libcwav].
-The goal of this library is to provide an interface for playing '''(b)cwav''' files in 3ds homebrew sofware. The way it is designed allows to play these files in non-application environments, such as ''3GX game plugins'' or ''applets'', as it provides support for the '''CSND''' system service. Unlike ''(b)cstm'' files which are streamed in chunks from their storage media, '''(b)cwav''' files are fully loaded into the linear RAM. Therefore, '''(b)cwav''' files are only meant for small sound effects. This library provides support for the '''ADPCM''' encodings, which heavily reduce the required memory to play the file.
-= Supported Features =
-== Supported CWAV Audio Encodings ==
+==User guide==
+===CWAV Audio Encodings===
 The following audio encodings are supported.
+* PCM8/PCM16 - Uncompressed 8/16 bit PCM. Useful if memory usage is not a problem.
+* DSP ADPCM - Lossy compression format, useful if the available memory is limited. Can only be played with DSP.
+* IMA ADPCM - Lossy compression format, similar to DSP ADPCM. Can only be played with CSND.
-=== PCM8/PCM16 ===
+===System Services===
-Uncompressed '''8/16 bit PCM'''. Useful if memory usage is not a problem.
-=== DSP ADPCM ===
-Lossy compression format, useful if the available memory is limited. Can only be played with '''DSP'''.
-=== IMA ADPCM ===
-Lossy compression format, similar to '''DSP ADPCM'''. Can only be played with '''CSND'''.
-== Supported System Services ==
 The following system services used to play the audio are supported.
+* DSP - This system service is used by normal applications. It is recommended to use this system service, as it properly supports suspending applications and sleep mode.
+* CSND - This system service is used by applets to play audio. It has the advantage of playing audio on top of running/suspended applications, whitout causing any interferences.
+** Use this system service if you want to play audio in applets or 3GX game plugins.
+** Make sure to use <code>cwavDoAptHook()</code> or <code>cwavNotifyAptEvent()</code> to handle apt events (app suspend, sleep or exit).
-=== DSP ===
+===Create (b)cwav files===
+You can use [https://github.com/mariohackandglitch/cwavtool cwavtool] to create (b)cwav files from other audio formats. It supports all possible encodings and loop points.
-This system service is used by normal applications. It is recommended to use this system service, as it properly supports suspending applications and sleep mode.
-=== CSND ===
-This system service is used by ''applets'' to play audio. It has the advantage of playing audio on top of running/suspended applications, whitout causing any interferences. Use this system service if you want to play audio in ''applets'' or ''3GX game plugins''. Make sure to use ''<code>cwavDoAptHook()</code>'' or ''<code>cwavNotifyAptEvent()</code>'' to handle apt events (app suspend, sleep or exit)!
-= Installation and Usage =
-# Make sure you have [https://devkitpro.org/wiki/Getting_Started devkitpro] installed and working.
-# Clone or download the repo and open a command prompt.
-# Run <code>make install</code> and confirm there aren't any errors.
-# In your project makefile, add the following to the <code>LIBDIRS</code> line (or similar): <code>$(DEVKITPRO)/libcwav</code>
-# In your project makefile, add the following to the <code>LIBS</code> line (or similar): <code>-lcwav</code> if the already listed libraries start with <code>-l</code> or just <code>cwav</code> if they don't.
-# Add <code>#include &quot;cwav.h&quot;</code> and/or <code>#include &quot;cwav_file.h&quot;</code> in your source files to use the library. You can check all the available function calls in the documentation provided in [[include/cwav.h|cwav.h]] and [[include/cwav_file.h|cwav_file.h]]. Also, you can see an example application in [[example_libcwav|example_libcwav]].
-= Creating (b)cwav files =
-You can use [https://github.com/mariohackandglitch/cwavtool cwavtool] to create '''(b)cwav''' files from other audio formats. It supports all possible encodings and loop points.
-= Credits =
-* [https://github.com/devkitPro/libctru libctru]: '''CSND''' and '''DSP''' implementation.
-* [https://www.3dbrew.org/wiki/BCWAV 3dbrew.org]: '''(b)cwav''' file specification.
-= License =
-This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages arising from the use of this software. Permission is granted to anyone to use this software for any purpose, including commercial applications, and to alter it and redistribute it freely, subject to the following restrictions:
+==Changelog==
+'''v1.0 2021/01/27'''
+* Initial release.
-# The origin of this software must not be misrepresented; you must not claim that you wrote the original software. If you use this software in a product, an acknowledgment in the product documentation would be appreciated but is not required.
+==Credits==
-# Altered source versions must be plainly marked as such, and must not be misrepresented as being the original software.
+* [https://github.com/devkitPro/libctru libctru] - CSND and DSP implementation.
-# This notice may not be removed or altered from any source distribution.
+* [https://www.3dbrew.org/wiki/BCWAV 3dbrew.org] - (b)cwav file specification.