C-Audio-Player

Project Overview

This project is a simple audio player implemented in C, providing both synchronous and asynchronous playback capabilities. It offers basic controls for audio playback, including play, pause, resume, volume control, and stop functionality.

{
  // ...

  play_sync("sound.mp3", 100);
  printf("This is printed after sound.mp3 is done\n");

  play_async("sound2.mp3", 50.5);
  printf("This is printed while sound2.mp3 is playing\n");

  // ...
}

Features

• Synchronous and asynchronous audio playback
• Pause and resume functionality
• Volume control
• Ability to stop playback
• Monitor playback state

API Documentation

The Simple Audio Player exposes the following API:

Initialization and Cleanup

void init_ao();
void destroy_ao();

• init_ao(): Initialize the audio output system. Must be called before using any other functions.
• destroy_ao(): Clean up and release resources used by the audio output system. Should be called at the end of the program.

Playback Functions

int play_sync(const char *filename, double volume);
t_sound *play_async(const char *filename, double volume);

// Volume is any double between 0 and 100, values out of range are scaled back

• play_sync(): Play an audio file synchronously. Returns -1 on error.
• play_async(): Start asynchronous playback of an audio file. Returns a pointer to a t_sound structure or NULL on error.

Playback Control

int   running_sounds(t_action action, t_sound *sound);

• running_sounds(): Control playback of a sound. The action parameter can be one of the following (returns -1 on error):

1- PAUSE: Pause the playback.

2- RESUME: Resume paused playback.

3- STOP: Stop the playback and clean up resources.

(IMPORTANT: After STOPing a sound, the matching t_sound instance is completely destroyed. Any usage of the variable after this will result in an undefined behavior)

int	set_volume_value(t_sound *sound, double value);

• set_volume_value(): Sets the sound's volume. value should be 0 <= value <= 100.

Monitor playback state

t_state	get_state(t_sound *sound);

• get_state(): Returns the state of a sound. The t_state return type is one of the following:

1- PLAYING: Currently playing.

2- PAUSED: Currently paused.

3- END: Playback has ended.

4- ERROR: Error occured while checking state.

Examples

// Include the header file
#include "simpleaudio.h"

// You should always call these two functions ONCE to initialize
// and destroy output resources at the beginning and end of your
// code respectively.
int main(int ac, char **av)
{
  init_ao();

  // Your code goes here

  destroy_ao();
}

Playing an audio file synchronously with max volume, taken from the commad line arguments:

int main(int ac, char **av)
{
  init_ao();

  int ret = play_sync(av[1], 100);
  if (ret == -1)
    printf("error\n");

  destroy_ao();
}

Same, but async:

int main(int ac, char **av)
{
  init_ao();

  t_sound  *sound = play_async(av[1], 100);
  if (sound == NULL)
    printf("error");

  destroy_ao();
}

You can then manipulate the playing sound using the t_sound instance you have, you can pause, resume, change volume and stop:

int main(int ac, char **av)
{
  init_ao();

  t_sound  *sound = play_async(av[1], 100);
  if (sound == NULL)
    printf("error");

  // Pause
  if (running_sounds(PAUSE, sound) == -1)
    printf("error");

  // Resume
  if (running_sounds(RESUME, sound) == -1)
    printf("error");

  // Change volume to 25%
  if (set_volume_value(sound, 25) == -1)
    printf("error");

  // Stop
  if (running_sounds(STOP, sound) == -1)
    printf("error");

  destroy_ao();
}

We'll add some sleep() functions to observe sound's changes. Our full program would be:

#include "simpleaudio.h"
#include <stdio.h>

int main(int ac, char **av)
{
  init_ao();

  printf("Let's play audio\n");
  t_sound  *sound = play_async(av[1], 100);
  if (sound == NULL)
    printf("error");
  sleep(1);

  // Pause
  printf("Let's pause\n");
  if (running_sounds(PAUSE, sound) == -1)
    printf("error");
  sleep(1);

  // Resume
  printf("Let's resume\n");
  if (running_sounds(RESUME, sound) == -1)
    printf("error");
  sleep(1);

  // Change volume to 25%
  printf("Let's change volume\n");
  if (set_volume_value(sound, 25) == -1)
    printf("error");
  sleep(1);

  // Stop
  printf("Let's stop\n");
  if (running_sounds(STOP, sound) == -1)
    printf("error");
  sleep(1);

  destroy_ao();
}

Lastly, you can wait for an async playback to end, like this:

{
  // ...

  // wait for playback to end
  while (get_state(sound) != END)
    usleep(1000); // adjustable
 
  // ...
}

How to use

Install locally

First, you need to install two dependencies that the library needs:

sudo apt-get install libao-dev libmpg123-dev

Clone repo

Then clone this repo locally:

git clone https://github.com/saad-out/C-Audio-Player
cd C-Audio-Player

Building the library

Once you've cloned the repository, you can build the library using the provided Makefile:

make

This command will compile the source files and generate static libsimpleaudio.a library in the lib/ directory.

Linking with your program

To use the library in your own program, you need to include the header file and link against the library.

1- Copy the include/simpleaudio.h header file to your project directory or add the include/ directory to your include path.

2- Copy the lib/libsimpleaudio.a file to your project directory or a directory in your library path.

3- In your C file, include the header:

#include "simpleaudio.h"

4-Compile your program, linking it with the Simple Audio Player library. Here's an example compilation command:

gcc -o your_program your_program.c -L. -lsimpleaudio -lmpg123 -lao -lpthread -lm

Make sure to replace your_program and your_program.c with your actual program name and source file. Note: The -lmpg123 -lao -lpthread -lm flags are necessary because our lib depends on these libraries. Make sure you have them installed on your system.

Docker image

This Docker image contains the Simple Audio Player library, allowing you to easily compile and run C programs that use this library.

Pulling the Image

To pull the image from Docker Hub, use the following command (you might need to use sudo):

docker pull saadout/simple-audio-player:latest

Using the Image

1- Create a C file that includes the Simple Audio Player library. For example, program.c:

#include <simpleaudio.h>
#include <stdio.h>

int main() {
    printf("Simple Audio Player library is successfully included!\n");
    return 0;
}

2- Run a container from the image, mounting your current directory:

docker run -it --rm -v $(pwd):/app saadout/simple-audio-player

3- Inside the container, compile your program:

gcc -o program program.c -lsimpleaudio -lmpg123 -lao -lpthread -lm

4- Run your program:

./program

Automating Compilation and Execution

You can use the following command to compile and run your program in one step:

docker run -it --rm -v $(pwd):/app saadout/simple-audio-player sh -c "gcc -o /app/program /app/program.c -lsimpleaudio -lmpg123 -lao -lpthread -lm && /app/program"

Replace program.c and program with your actual file names if different.

Note

This image is based on Ubuntu and includes all necessary dependencies to compile and run programs using the Simple Audio Player library.