> For the complete documentation index, see [llms.txt](https://sandbox-docs.verifone.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://sandbox-docs.verifone.com/s-adk-5.1-programmers-guide/readme/system_overview/pg_all_components/pg_sound_users_guide.md).
# ADK-SOUND Programmers Guide
## Preface
This document is for programmers and developers who want to understand and use the ADK-Sound framework.
### Audience
This guide provides information on the usage of the ADK-Sound system.
### Organization
[Chapter 1: Introduction](#snd_introduction)
[Chapter 2: Supported Hardware](#snd_hw_support)
[Chapter 3: Getting Started](#snd_getting_started)
[Chapter 4: Programming](#snd_programming)
[Chapter 5: System Setup and Requirements](#snd_setup)
## Introduction
ADK-Sound allows simple playback of MP3 and WAV files. Playback can be started and stopped and the playback position within the file may be updated.
## Supported Hardware
VOS and VOS2 terminals with speaker are supported. Currently Verix terminals are not supported.
## Getting Started
The following minimal program shows how to play a sound in a loop
```cpp
#include
#include
void cb(void *data, SND *handle, enum SNDError reason)
{
if(reason!=SND_OK) return;
sndSeek(handle,0,SEEK_SET); // rewind to start
sndStart(handle); // start playback again
}
int main()
{
SND *handle=sndOpenFile("sound.mp3");
sndSetCallback(handle,cb,0); // callback gets invoked when the sound stopped
sndStart(handle); // start playback
while(1) sleep(100000); // do nothing, sound plays in background
}
```
## Programming
### Opening and Closing files
To play a sound the file needs to be opened using [sndOpenFile()](/s-adk-5.1-programmers-guide/readme/files/dir_15b7eb99384c20f55db7776b7b1ecdad/dir_7d99a5752ef00d9a9478541a793df8d8/dir_b95d7ee73b2963b5e37f0a7269e7a4c6/sound_8h.md#a2e0076124852060867cc4039c1719646). In case of success a handle is returned, that needs to be provided to the other functions. The handle needs to be closed using [sndClose()](/s-adk-5.1-programmers-guide/readme/files/dir_15b7eb99384c20f55db7776b7b1ecdad/dir_7d99a5752ef00d9a9478541a793df8d8/dir_b95d7ee73b2963b5e37f0a7269e7a4c6/sound_8h.md#aac877336c270fa31b7396dd9e01a0ee5) when done to release the allocated resources. When closing the handle, sound playback is stopped automatically, when still playing.
### Starting and Stopping playback
[sndStart()](/s-adk-5.1-programmers-guide/readme/files/dir_15b7eb99384c20f55db7776b7b1ecdad/dir_7d99a5752ef00d9a9478541a793df8d8/dir_b95d7ee73b2963b5e37f0a7269e7a4c6/sound_8h.md#a6074c9bf1534c6e8e10ed0e3c72897cf) starts playback at the current position. When the file has just been opened, this is the start of the file. The position can be updated anytime using [sndSeek()](/s-adk-5.1-programmers-guide/readme/files/dir_15b7eb99384c20f55db7776b7b1ecdad/dir_7d99a5752ef00d9a9478541a793df8d8/dir_b95d7ee73b2963b5e37f0a7269e7a4c6/sound_8h.md#a8f0945ea304cff2a5b223186b73087f7). [sndStop()](/s-adk-5.1-programmers-guide/readme/files/dir_15b7eb99384c20f55db7776b7b1ecdad/dir_7d99a5752ef00d9a9478541a793df8d8/dir_b95d7ee73b2963b5e37f0a7269e7a4c6/sound_8h.md#a3fbd83f5f49d41b445b1e9dd8bc82c0f) is used to stop playback. Stopping playback does not reset the current position to the start of the file so that [sndStart()](/s-adk-5.1-programmers-guide/readme/files/dir_15b7eb99384c20f55db7776b7b1ecdad/dir_7d99a5752ef00d9a9478541a793df8d8/dir_b95d7ee73b2963b5e37f0a7269e7a4c6/sound_8h.md#a6074c9bf1534c6e8e10ed0e3c72897cf) can be used to resume playback at the position it was stopped.
### Miscellaneous functions
The current position can be read using [sndTell()](/s-adk-5.1-programmers-guide/readme/files/dir_15b7eb99384c20f55db7776b7b1ecdad/dir_7d99a5752ef00d9a9478541a793df8d8/dir_b95d7ee73b2963b5e37f0a7269e7a4c6/sound_8h.md#a701ee6a24c4fcffacf3ec555c92caf97). The position is given in seconds from the start of the file.
[sndLength()](/s-adk-5.1-programmers-guide/readme/files/dir_15b7eb99384c20f55db7776b7b1ecdad/dir_7d99a5752ef00d9a9478541a793df8d8/dir_b95d7ee73b2963b5e37f0a7269e7a4c6/sound_8h.md#ae7e8fbfe734a79cf6648515fb7758f12) returns the estimated length of the file. Note that the estimated length may differ from the real length since for MP3 files it may not be possible to determine the real length without scanning the whole file, which may be slow.
If an application needs to know the real length, it can use [sndSeek()](/s-adk-5.1-programmers-guide/readme/files/dir_15b7eb99384c20f55db7776b7b1ecdad/dir_7d99a5752ef00d9a9478541a793df8d8/dir_b95d7ee73b2963b5e37f0a7269e7a4c6/sound_8h.md#a8f0945ea304cff2a5b223186b73087f7) to seek to the end of the file and use [sndTell()](/s-adk-5.1-programmers-guide/readme/files/dir_15b7eb99384c20f55db7776b7b1ecdad/dir_7d99a5752ef00d9a9478541a793df8d8/dir_b95d7ee73b2963b5e37f0a7269e7a4c6/sound_8h.md#a701ee6a24c4fcffacf3ec555c92caf97) to obtain the position.
### System Setup and Requirements
ADK-Sound uses ALSA for sound output. Therefore, the terminal needs to have ALSA support. By default concurrent playback of several sound sources is not supported. To enable concurrent playback, the ALSA dmix plugin must have been set up as default output device. This plugin mixes several sound sources into one stream that is sent to the sound hardware.
There are two ways of setting up the ALSA dmix plugin:
* global configuration in /etc/asound.conf
* local configuration in \~/.asoundrc
The global configuration needs to be provided by the OS and affects all programs on the terminal. The local configuration can be provided by any application but affects only applications run by the same user. However, if one user still uses the default output and not dmix, this user will use the sound output exclusively.
A starting point for an ALSA configuration looks like this:
```fragment
pcm.snd_card {
type hw
card 0
device 0
}
ctl.snd_card {
type hw
card 0
device 0
}
# Define dmix-Plugin
pcm.dmixer {
type dmix
ipc_key 1024
ipc_perm 0666 # Allow other users to use dmix
slave.pcm "snd_card"
}
pcm.dsnooper {
type dsnoop
ipc_key 2048
ipc_perm 0666
slave.pcm "snd_card"
}
pcm.duplex {
type asym
playback.pcm "dmixer"
capture.pcm "dsnooper"
}
pcm.!default {
type plug
slave.pcm "duplex"
}
```
For more information check the ALSA documentation.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://sandbox-docs.verifone.com/s-adk-5.1-programmers-guide/readme/system_overview/pg_all_components/pg_sound_users_guide.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.