TizenRT Public API  v2.0 M2
TinyAlsa

Provides APIs for Audio Framework. More...

Files

file  tinyalsa.h
 All macros, structures and functions that make up the PCM interface.
 

Data Structures

struct  pcm_config
 Encapsulates the hardware and software parameters of a PCM. More...
 

Macros

#define PCM_OUT   0x00000010
 
#define PCM_IN   0x00000020
 
#define PCM_MMAP   0x00000001
 
#define PCM_NOIRQ   0x00000002
 
#define PCM_NORESTART   0x00000004
 
#define PCM_STATE_RUNNING   0x03
 
#define PCM_STATE_XRUN   0x04
 
#define PCM_STATE_DRAINING   0x05
 
#define PCM_STATE_SUSPENDED   0x07
 
#define PCM_STATE_DISCONNECTED   0x08
 

Enumerations

Functions

struct pcm * pcm_open (unsigned int card, unsigned int device, unsigned int flags, const struct pcm_config *config)
 Opens a PCM for playback or recording. More...
 
struct pcm * pcm_open_by_name (const char *name, unsigned int flags, const struct pcm_config *config)
 Opens a PCM by it's name. More...
 
int pcm_close (struct pcm *pcm)
 Closes a PCM returned by pcm_open. More...
 
int pcm_is_ready (const struct pcm *pcm)
 Checks if a PCM file has been opened without error. More...
 
unsigned int pcm_get_channels (const struct pcm *pcm)
 Gets the channel count of the PCM. More...
 
const struct pcm_configpcm_get_config (const struct pcm *pcm)
 Gets the PCM configuration. More...
 
unsigned int pcm_get_rate (const struct pcm *pcm)
 Gets the sample rate of the PCM. More...
 
enum pcm_format pcm_get_format (const struct pcm *pcm)
 Gets the format of the PCM. More...
 
int pcm_get_file_descriptor (const struct pcm *pcm)
 Gets the file descriptor of the PCM. More...
 
const char * pcm_get_error (const struct pcm *pcm)
 Gets the error message for the last error that occured. More...
 
unsigned int pcm_get_buffer_size (const struct pcm *pcm)
 Gets the buffer size of the PCM. More...
 
unsigned int pcm_frames_to_bytes (const struct pcm *pcm, unsigned int frames)
 Determines how many bytes are occupied by a number of frames of a PCM. More...
 
unsigned int pcm_bytes_to_frames (const struct pcm *pcm, unsigned int bytes)
 Determines how many frames of a PCM can fit into a number of bytes. More...
 
int pcm_writei (struct pcm *pcm, const void *data, unsigned int frame_count)
 Writes audio samples to PCM. More...
 
int pcm_readi (struct pcm *pcm, void *data, unsigned int frame_count)
 Reads audio samples from PCM. More...
 
int pcm_drop (struct pcm *pcm)
 Stops a PCM. Any data present in the buffers will be dropped. More...
 
int pcm_drain (struct pcm *pcm)
 Stop a PCM preserving pending frames. More...
 
int pcm_prepare (struct pcm *pcm)
 Prepares a PCM, if it has not been prepared already. More...
 
unsigned int pcm_format_to_bits (enum pcm_format format)
 Determines the number of bits occupied by a pcm_format. More...
 
unsigned int pcm_get_subdevice (const struct pcm *pcm)
 Gets the subdevice on which the pcm has been opened. More...
 
int pcm_mmap_write (struct pcm *pcm, const void *data, unsigned int count)
 Writes audio samples to the PCM using the mmap buffer. More...
 
int pcm_mmap_read (struct pcm *pcm, void *data, unsigned int count)
 Reads audio samples from the PCM using the mmap buffer. More...
 
int pcm_mmap_begin (struct pcm *pcm, void **areas, unsigned int *offset, unsigned int *frames)
 Application request to access a portion of direct (mmap) area. More...
 
int pcm_mmap_commit (struct pcm *pcm, unsigned int offset, unsigned int frames)
 Application has completed the access to area requested with pcm_mmap_begin. More...
 
int pcm_wait (struct pcm *pcm, int timeout)
 Waits for buffer to become available for mmap access. More...
 
int pcm_avail_update (struct pcm *pcm)
 Returns the number of frames ready to be written or read. More...
 

Detailed Description

Provides APIs for Audio Framework.

Macro Definition Documentation

#define PCM_IN   0x00000020

Specifies that the PCM is an input. May not be bitwise AND'd with PCM_OUT. Used in pcm_open.

Definition at line 81 of file tinyalsa.h.

#define PCM_MMAP   0x00000001

Specifies that the PCM will use mmap read and write methods. Used in pcm_open.

Definition at line 87 of file tinyalsa.h.

#define PCM_NOIRQ   0x00000002

Specifies no interrupt requests. May only be bitwise AND'd with PCM_MMAP. Used in pcm_open.

Definition at line 94 of file tinyalsa.h.

#define PCM_NORESTART   0x00000004

When set, calls to pcm_write for a playback stream will not attempt to restart the stream in the case of an underflow, but will return -EPIPE instead. After the first -EPIPE error, the stream is considered to be stopped, and a second call to pcm_write will attempt to restart the stream. Used in pcm_open.

Definition at line 107 of file tinyalsa.h.

#define PCM_OUT   0x00000010

A flag that specifies that the PCM is an output. May not be bitwise AND'd with PCM_IN. Used in pcm_open.

Definition at line 74 of file tinyalsa.h.

#define PCM_STATE_DISCONNECTED   0x08

Means a PCM has been disconnected.

Definition at line 133 of file tinyalsa.h.

#define PCM_STATE_DRAINING   0x05

For outputs, this means audio samples are played. A PCM is in a draining state when it is coming to a stop.

Definition at line 123 of file tinyalsa.h.

#define PCM_STATE_RUNNING   0x03

For inputs, this means the PCM is recording audio samples. For outputs, this means the PCM is playing audio samples.

Definition at line 113 of file tinyalsa.h.

#define PCM_STATE_SUSPENDED   0x07

Means a PCM is suspended.

Definition at line 128 of file tinyalsa.h.

#define PCM_STATE_XRUN   0x04

For inputs, this means an overrun occured. For outputs, this means an underrun occured.

Definition at line 118 of file tinyalsa.h.

Enumeration Type Documentation

enum pcm_format

Audio sample format of a PCM.

The first letter specifiers whether the sample is signed or unsigned. The letter 'S' means signed. The letter 'U' means unsigned. The following number is the amount of bits that the sample occupies in memory. Following the underscore, specifiers whether the sample is big endian or little endian. The letters 'LE' mean little endian. The letters 'BE' mean big endian. This enumeration is used in the pcm_config structure.

Enumerator
PCM_FORMAT_NONE 

Error Case

PCM_FORMAT_S8 

Signed, 8-bit

PCM_FORMAT_S16_LE 

Signed 16-bit, little endian

PCM_FORMAT_S16_BE 

Signed, 16-bit, big endian

PCM_FORMAT_S24_LE 

Signed, 24-bit (32-bit in memory), little endian

PCM_FORMAT_S24_BE 

Signed, 24-bit (32-bit in memory), big endian

PCM_FORMAT_S24_3LE 

Signed, 24-bit, little endian

PCM_FORMAT_S24_3BE 

Signed, 24-bit, big endian

PCM_FORMAT_S32_LE 

Signed, 32-bit, little endian

PCM_FORMAT_S32_BE 

Signed, 32-bit, big endian

PCM_FORMAT_MAX 

Max of the enumeration list, not an actual format.

Definition at line 146 of file tinyalsa.h.

Function Documentation

int pcm_avail_update ( struct pcm *  pcm)

Returns the number of frames ready to be written or read.

#include <tinyalsa/tinyalsa.h>

Parameters
[in]pcmA PCM handle
Returns
On success, positive number is returned. On failure, a negative number returned
Since
TizenRT v2.0
unsigned int pcm_bytes_to_frames ( const struct pcm *  pcm,
unsigned int  bytes 
)

Determines how many frames of a PCM can fit into a number of bytes.

#include <tinyalsa/tinyalsa.h>

Parameters
[in]pcmA PCM handle.
[in]bytesThe number of bytes.
Returns
The number of frames that may fit into bytes
Since
TizenRT v1.1
int pcm_close ( struct pcm *  pcm)

Closes a PCM returned by pcm_open.

#include <tinyalsa/tinyalsa.h>

Parameters
[in]pcmA PCM returned by pcm_open.
Returns
Always returns 0.
Since
TizenRT v1.1
int pcm_drain ( struct pcm *  pcm)

Stop a PCM preserving pending frames.

#include <tinyalsa/tinyalsa.h>

Parameters
[in]pcmA PCM handle.
Returns
On success, zero; on failure, a negative number.
Since
TizenRT v2.0
int pcm_drop ( struct pcm *  pcm)

Stops a PCM. Any data present in the buffers will be dropped.

#include <tinyalsa/tinyalsa.h>

Parameters
[in]pcmA PCM handle.
Returns
On success, zero; on failure, a negative number.
Since
TizenRT v2.0
unsigned int pcm_format_to_bits ( enum pcm_format  format)

Determines the number of bits occupied by a pcm_format.

#include <tinyalsa/tinyalsa.h>

Parameters
[in]formatA PCM format
Returns
The number of bits associated with format
Since
TizenRT v1.1
unsigned int pcm_frames_to_bytes ( const struct pcm *  pcm,
unsigned int  frames 
)

Determines how many bytes are occupied by a number of frames of a PCM.

#include <tinyalsa/tinyalsa.h>

Parameters
[in]pcmA PCM handle.
[in]framesThe number of frames of a PCM.
Returns
The bytes occupied by frames.
Since
TizenRT v1.1
unsigned int pcm_get_buffer_size ( const struct pcm *  pcm)

Gets the buffer size of the PCM.

#include <tinyalsa/tinyalsa.h>

Parameters
[in]pcmA PCM handle.
Returns
The buffer size of the PCM.
Since
TizenRT v1.1
unsigned int pcm_get_channels ( const struct pcm *  pcm)

Gets the channel count of the PCM.

#include <tinyalsa/tinyalsa.h>

Parameters
[in]pcmA PCM handle.
Returns
The channel count of the PCM.
Since
TizenRT v1.1
const struct pcm_config* pcm_get_config ( const struct pcm *  pcm)

Gets the PCM configuration.

#include <tinyalsa/tinyalsa.h>

Parameters
[in]pcmA PCM handle.
Returns
On success, The PCM configuration returned. On failure, NULL returned.
Since
TizenRT v1.1
const char* pcm_get_error ( const struct pcm *  pcm)

Gets the error message for the last error that occured.

#include <tinyalsa/tinyalsa.h>

Parameters
[in]pcmA PCM handle.
Returns
The error message of the last error that occured.
Since
TizenRT v1.1
int pcm_get_file_descriptor ( const struct pcm *  pcm)

Gets the file descriptor of the PCM.

#include <tinyalsa/tinyalsa.h>

Parameters
[in]pcmA PCM handle.
Returns
The file descriptor of the PCM.
Since
TizenRT v1.1
enum pcm_format pcm_get_format ( const struct pcm *  pcm)

Gets the format of the PCM.

#include <tinyalsa/tinyalsa.h>

Parameters
[in]pcmA PCM handle.
Returns
The format of the PCM.
Since
TizenRT v1.1
unsigned int pcm_get_rate ( const struct pcm *  pcm)

Gets the sample rate of the PCM.

#include <tinyalsa/tinyalsa.h>

Parameters
[in]pcmA PCM handle.
Returns
The rate of the PCM.
Since
TizenRT v1.1
unsigned int pcm_get_subdevice ( const struct pcm *  pcm)

Gets the subdevice on which the pcm has been opened.

#include <tinyalsa/tinyalsa.h>

Parameters
[in]pcmA PCM handle.
Returns
The subdevice on which the pcm has been opened.
Since
TizenRT v1.1
int pcm_is_ready ( const struct pcm *  pcm)

Checks if a PCM file has been opened without error.

#include <tinyalsa/tinyalsa.h>

Parameters
[in]pcmA PCM handle.
Returns
On success, 0 returned. On failure, 1 returned
Since
TizenRT v1.1
int pcm_mmap_begin ( struct pcm *  pcm,
void **  areas,
unsigned int *  offset,
unsigned int *  frames 
)

Application request to access a portion of direct (mmap) area.

#include <tinyalsa/tinyalsa.h>

Parameters
[in]pcmA PCM handle
[out]areasReturned mmap channel areas
[out]offsetReturned mmap area offset in frames
[out]framesMmap area portion size in frames
Returns
On success, zero is returned. On failure, a negative number returned
Since
TizenRT v2.0
int pcm_mmap_commit ( struct pcm *  pcm,
unsigned int  offset,
unsigned int  frames 
)

Application has completed the access to area requested with pcm_mmap_begin.

#include <tinyalsa/tinyalsa.h>

Parameters
[in]pcmA PCM handle
[in]offsetArea offset in frames. This must be same as the offset returned by pcm_mmap_begin
[in]framesMmap area portion size in frames that application wishes to commit
Returns
On success, zero is returned. On failure, a negative number returned
Since
TizenRT v2.0
int pcm_mmap_read ( struct pcm *  pcm,
void *  data,
unsigned int  count 
)

Reads audio samples from the PCM using the mmap buffer.

#include <tinyalsa/tinyalsa.h>

Parameters
[in]pcmA PCM handle
[in]dataPointer to the buffer to read into
[in]countSize of the buffer in bytes
Returns
On success, read number of frames returned. On failure, a negative number returned
Since
TizenRT v2.0
int pcm_mmap_write ( struct pcm *  pcm,
const void *  data,
unsigned int  count 
)

Writes audio samples to the PCM using the mmap buffer.

#include <tinyalsa/tinyalsa.h>

Parameters
[in]pcmA PCM handle
[in]dataPointer to the buffer containing data to be written
[in]countSize of the data in bytes
Returns
On success, written number of frames returned. On failure, a negative number returned
Since
TizenRT v2.0
struct pcm* pcm_open ( unsigned int  card,
unsigned int  device,
unsigned int  flags,
const struct pcm_config config 
)

Opens a PCM for playback or recording.

#include <tinyalsa/tinyalsa.h>

Parameters
[in]cardThe card that the pcm belongs to.
[in]deviceThe device that the pcm belongs to.
[in]flagsSpecify characteristics and functionality about the pcm.
[in]configThe hardware and software parameters to open the PCM with.
Returns
On success, A PCM structure returned. On failure, invalid PCM structure returned.
Since
TizenRT v1.1
struct pcm* pcm_open_by_name ( const char *  name,
unsigned int  flags,
const struct pcm_config config 
)

Opens a PCM by it's name.

#include <tinyalsa/tinyalsa.h>

Parameters
[in]nameThe name of the PCM.
[in]flagsSpecify characteristics and functionality about the pcm.
[in]configThe hardware and software parameters to open the PCM with.
Returns
On success, A PCM structure returned. On failure, NULL or invalid PCM structure returned.
Since
TizenRT v1.1
int pcm_prepare ( struct pcm *  pcm)

Prepares a PCM, if it has not been prepared already.

#include <tinyalsa/tinyalsa.h>

Parameters
[in]pcmA PCM handle.
Returns
On success, 0 returned. On failure, a negative number returned.
Since
TizenRT v1.1
int pcm_readi ( struct pcm *  pcm,
void *  data,
unsigned int  frame_count 
)

Reads audio samples from PCM.

#include <tinyalsa/tinyalsa.h>

Parameters
[out]pcmA PCM handle.
[out]dataThe audio sample array which will contain the audio data recieved from the input stream
[in]frame_countThe number of frames that the user wants to read
Returns
On success, number of frames read returned. On failure, a negative number returned.
Since
TizenRT v1.1
int pcm_wait ( struct pcm *  pcm,
int  timeout 
)

Waits for buffer to become available for mmap access.

#include <tinyalsa/tinyalsa.h>

Parameters
[in]pcmA PCM handle
[in]timeoutMaximum time in milliseconds to wait, a negative value means infinity
Returns
On success, one is returned. On timeout, zero is returned. On failure, a negative number returned
Since
TizenRT v2.0
int pcm_writei ( struct pcm *  pcm,
const void *  data,
unsigned int  frame_count 
)

Writes audio samples to PCM.

#include <tinyalsa/tinyalsa.h>

Parameters
[out]pcmA PCM handle.
[in]dataThe audio sample array
[in]frame_countThe number of frames occupied by the sample array.
Returns
On success, written number of frames returned. On failure, a negative number returned.
Since
TizenRT v1.1