Main Page Compound List File List Compound Members File Members

# cslsample.c File Reference

`#include <csl/cslsample.h>`
`#include <csl/cslmain.h>`
`#include <csl/cslutils.h>`
`#include <csl/cslprivate.h>`
`#include <sys/types.h>`
`#include <sys/stat.h>`
`#include <errno.h>`
`#include <fcntl.h>`
`#include <unistd.h>`

## Functions
CslErrorType | csl_sample_new (CslDriver *driver, const char *name, const char *role, const char *title, CslSample **sample_p)
| Create a new sample. More...
CslErrorType | csl_sample_new_from_file (CslDriver *driver, const char *name, const char *role, const char *title, CslSample **sample_p)
| Create a sample from a file. More...
int | csl_sample_write (CslSample *sample, unsigned int n_bytes, void *bytes)
| Write data into a sample. More...
CslErrorType | csl_sample_write_done (CslSample *sample)
| Finish writing data into a sample. More...
CslErrorType | csl_sample_play (CslSample *sample)
| Play a sound sample. More...
void | csl_sample_release (CslSample *sample)
| Free a sound sample. More...
CslErrorType | csl_sample_new_from_cache (CslDriver *driver, const char *name, const char *role, const char *title, CslSample **sample_p)
| Obtain a sample from the sample cache. More...
CslErrorType | csl_sample_cache_remove (CslSample *sample)
| Remove a sound sample from the sample cache. More...
CslErrorType | csl_sample_cache_add (CslSample *sample)
| Add a sound sample to the sample cache. More...
CslBool | csl_sample_is_playing (CslSample *sample)
| Check whether a sample is being played. More...
CslErrorType | csl_sample_stop (CslSample *sample)
| Stop playing a sample. More...
CslErrorType | csl_sample_wait_done (CslSample *sample)
| Wait until playing a sample is done. More...

## Detailed Description

The CSL sample API provides a simple means for playing PCM sound samples. You create samples from files or PCM sound data, and send them to the sound server to be played. You can reuse the sample multiple times and share samples with other apps if they are using the same sound server.

Typical usage will follow these steps:

- Call csl_sample_new to create an empty sample.
- Call csl_sample_write to write data into sample.
- Call csl_sample_write_done to indicate end of writing sample data.
- Alternatively you can call csl_sample_new_from_file instead of the above three steps, if you have an existing sound file.
- Call csl_sample_play to play the sample.
- Call csl_sample_release when finished using the sample.

Samples are cached in the sound server as long as they are active (i.e. until released using csl_sample_release). Using csl_sample_cache_add a sample can be permanently added to the sample cache (at least until the server is restarted). Samples can be loaded from the cache using csl_sample_new_from_cache and removed using csl_sample_cache_remove. The caching behaviour may vary depending on which backend is used.

## Function Documentation

CslErrorType csl_sample_cache_add | ( | CslSample * | sample | ) |

  | Add a sound sample to the sample cache. This adds a sample to the sample cache. It will remain cached even after calling csl_sample_release until csl_sample_cache_remove is called or the sound server is restarted. Parameters:
  sample | A pointer to a previously created CslSample.
Returns: Error code indicating success or failure.

CslErrorType csl_sample_cache_remove | ( | CslSample * | sample | ) |

  | Remove a sound sample from the sample cache. This tells the library to remove a sample from the sample cache. Parameters:
  sample | A pointer to a previously created CslSample.

CslBool csl_sample_is_playing | ( | CslSample * | sample | ) |

  | Check whether a sample is being played. This checks whether a sample is currently being played. If you have started a sample multiple times at once, this will return whether at least one of them is still being played. Parameters:
  sample | A pointer to a previously created CslSample.
Returns: True if the sample is still playing.

CslErrorType csl_sample_new | ( | CslDriver * | driver,
|  | const char * | name,
|  | const char * | role,
|  | const char * | title,
|  | CslSample ** | sample_p
| ) |

  | Create a new sample. This creates a new (empty) sample which can be played back later. In order to use the sample you need to write PCM data into it using csl_sample_write. Parameters:
  driver | A pointer to a previously opened CSL driver.
  name | A name for the new sample. You should give a reasonable name with extension (like "bong.wav"), as the implementation might depend on the extension for figuring out the type.
  sample_p | A pointer to a pointer to the newly created sample.
Returns: Error code indicating success or failure. See also: csl_sample_new_from_file , csl_sample_write

CslErrorType csl_sample_new_from_cache | ( | CslDriver * | driver,
|  | const char * | name,
|  | const char * | role,
|  | const char * | title,
|  | CslSample ** | sample_p
| ) |

  | Obtain a sample from the sample cache. This function attempts to find a sound sample in the sample cache. If found, it returns the sample, otherwise it returns an error status. Parameters:
  driver | A pointer to a previously opened CSL driver.
  name | The name for the new sample, which must match the name previously used when the sample was cached.
  sample_p | A pointer to a pointer to the cached sample.
Returns: Error code indicating success or failure. See also: csl_sample_new , csl_sample_new_from_file

CslErrorType csl_sample_new_from_file | ( | CslDriver * | driver,
|  | const char * | name,
|  | const char * | role,
|  | const char * | title,
|  | CslSample ** | sample_p
| ) |

  | Create a sample from a file. This creates a sample from an existing sound file (e.g. .wav file). It is equivalent to calling csl_sample_new, writing the file contents using csl_sample_write, and then calling csl_sample_write_done. Parameters:
  driver | A pointer to a previously opened CSL driver.
  name | A name for the new sample. This should be the name of an existing sound file, with extension (like "bong.wav"). After this call the sample is ready to be played.
  sample_p | A pointer to a pointer to the newly created sample.
Returns: Error code indicating success or failure. See also: csl_sample_new , csl_sample_write

CslErrorType csl_sample_play | ( | CslSample * | sample | ) |

  | Play a sound sample. This plays a sound sample. Note that playing a sample will return immediately. You can use csl_sample_is_playing to check whether it is still playing or csl_sample_wait_done to wait until it is done. Parameters:
  sample | A pointer to a previously created CslSample.
See also: csl_sample_write Returns: Error code indicating success or failure.

void csl_sample_release | ( | CslSample * | sample | ) |

  | Free a sound sample. This releases the resources associated with a sound sample. You should release a sample when it is no longer required. You must not use the sample after it has been release. A currently playing sample will not be stopped through this function though, use csl_sample_stop if you want that. Parameters:
  sample | A pointer to a previously created CslSample.

CslErrorType csl_sample_stop | ( | CslSample * | sample | ) |

  | Stop playing a sample. This stops playing a sample (which was started with csl_sample_play) immediately. Parameters:
  sample | A pointer to a previously created CslSample.
Returns: Error code indicating success or failure.

CslErrorType csl_sample_wait_done | ( | CslSample * | sample | ) |

  | Wait until playing a sample is done. This waits until playing a sample (which was started with csl_sample_play) is done. Parameters:
  sample | A pointer to a previously created CslSample.
Returns: Error code indicating success or failure.

int csl_sample_write | ( | CslSample * | sample,
|  | unsigned int | n_bytes,
|  | void * | bytes
| ) |

  | Write data into a sample. This writes PCM data into an empty sample, previously created using csl_sample_new. You can call this function multiple times if desired, and the data will be concatenated together. You indicate that no more data needs to be written by calling csl_sample_write_done. The data format is inferred from the name used when the sample is created with csl_sample_new. Parameters:
  sample | A pointer to a previously created CslSample.
  n_bytes | The number of bytes of sample data to be written.
  bytes | A pointer to the buffer of PCM data to be written into the sample.
Returns: The number of bytes written to the sample, normally the same as n_bytes. See also: csl_sample_new , csl_sample_write_done

CslErrorType csl_sample_write_done | ( | CslSample * | sample | ) |

  | Finish writing data into a sample. This is called after one or more calls to csl_sample_write to indicate that you are finished writing data into the sample. The sample is now ready to be played using csl_sample_play. Parameters:
  sample | A pointer to a previously created CslSample.
See also: csl_sample_write