Overview of Peep's Internals

Note: Much has changed with the advent of the 0.5.0 release. This release is a complete rewrite of the server code. Rereading this documentation should quickly get anyone up to speed.

The inner workings of peepd are based upon the interactions of three execution threads: the server, the sound engine, and the mixer. The server part handles all communications, including auto-discovery and keeping track of client leases when using UDP. Upon receipt of an event, the server places the event into a queue to be processed by the sound engine. The engine works closely in conjunction with the mixer to keep track of the priority of incoming and currently playing sounds. The engine also tries to find the best available mixing channel on which to play the incoming events and informs the mixer of the necessary parameters to properly represent the information. Should a suitable mixing channel not be found, the engine will place the events into a priority queue, ensuring that the mixer will play the most important events as soon as mixing channels free up. The mixer performs the processing necessary to produce Peep's output. This process involves scaling each sound's volume, as well as fading between state sounds. The mixer must also check the engine's event queue and ensure that queued, older events have priority as soon as mixing channels free up.

A high level illustration of Peep's internals are shown below.

Each file in the Peep server has the following functions:

• alsa.c
  • Contains the code for interfacing with the ALSA libraries. This code works with version of ALSA that ships with most current Linux distros (0.9.x).

• cmdline.c
  • Contains the code for parsing command-line routines and populating an options data structure. This data structure is then referenced in the main program to determine which options were set and what their respective values are. The interface used is similar to GNU's command line option generator but avoids GNU for portability.

• cmdline.h
  • Contains the definition of the command-line argument structure that contains fields indicating whether options were set and their respective values.

• copyright.h
  • Contains a character string that includes the copyright disclaimer so the disclaimer is viewable when the strings utility is run on the binary.

• debug.c
  • Debugging routines as well as the assert macro for assertion debugging. The code here is fairly self-explanitory.

• debug.h
  • Defines 10 different debugging flags and the 6 different debugging levels that provide an output that combines the flags. Also provides definitions for the debugging routines.

• engine.c
  • Contains the sound engine that determines which events play where in the mixer datastructure. If no channel is found, the event is enqueued in the engine queue for later playback and time stamped. The algorithm is pretty well detailed in the comments.

• engine.h
  • Contains the definitions for engine.c but also contains the definition of an EVENT, with a description of what each field is. The sound table for mapping event identifiers to internal reference numbers is also implemented within the engine.

• engine_queue.c
  • Contains the queuing structure between the events received by the server, waiting to be processed by the engine thread.

• engine_queue.h
  • Definitions for the queue.

• main.c
  • Starts up the server by initialize the command-line parsing routines, and checking options. It then daemonizes itself if needed, and starts the engine and mixer threads. Finally, it acts as the server thread. This file also contains the main shutdown routine.

• main.h
  • Just some definitions for stuff in main.c, as well as some global settings. Also contains some default paths to files, etc.

• mixer.c
  • Contains all of the mixer functionality, as well the sound effects architecture. The sound effects architecture is a flexible way to add new real-time effects to Peep and currently features the linear fading code.

• mixer.h
  • Definitions for the mixer and the defined effects flags.

• mixer_queue.c
  • Servers as the window for holding events that could not be played when received. The events are put here by the engine thread and time stamped to be later played when a mixer channel frees up.

• mixer_queue.h
  • Definitions for the mixer queue.

• notice.c
  • This contains the code for creating a notice data structure, which is parsed from an XML notice string. This module also contains the functionality needed to insert code hooks into peepd to allow for post-processing.

• notice.h
  • Contains the definition of a notice data structure used for post-processing of an event.

• oss.c
  • Contains code for interfacing with /dev/audio and provides an abstraction for writing raw PCM to the device driver. This is one of the sound modules provided.

• parser.c
  • Contains the code to parse the peep.conf style configuration format. It also provides some common routines to the XML theme parser.

• parser.h
  • Contains definitions for the parser code.

• playback.c
  • Contains all the code for recording events and performing playback. The playback code hooks into the engine code in an if statement that decides whether or not the event needs to be recorded/is ready for playback.

• playback.h
  • Definitions for the playback code, including the definition of the playback file header.

• server.c
  • Contains the server routines common to all server modules that implement specific server protocols. This includes initializing the UDP port for broadcasting. Finally, it calls the real server module functions to perform the actual connection handling.

• server.h
  • Contains the Peep protocol definitions. These include the definition of a packet header, as well as packet contents.

• sound.h
  • General sound header that provides an the definitions of the abstractions for the sound modules.

• ssl_server.c
  • Implements the server routines that use SSL as the main communication protocol.

• ssl_server.h
  • Contains definitions for the SSL server routines.

• tcp_server.c
  • Implements the server routines that use TCP as the main communication protocol.

• tcp_server.h
  • Contains definitions for the TCP server routines.

• thread.c
  • Wraps POSIX threading code into simple functions. Also wraps semaphore code.

• thread.h
  • Contains the definiton for the threading functions.

• udp_server.c
  • Implements the server routines that use UDP only as the main communication protocol, as well as the leasing needed for client management.

• udp_server.h
  • Contains definitions for the UDP only server routines as well as the leasing protocol definitions.

• xml.c
  • Contains some handy routines to clean up strings for XML parsing.

• xml.h
  • Definitions of the XML helper routines.

• xml_notice.c
  • Contains the code for parsing XML notice messages received from client events and populates the notice data structure, which is then passed to the server code hooks.

• xml_notice.h
  • Contains the defintion of the XML tags, as well as the parsing routines.

• xml_theme.c
  • Contains the code for parsing XML theme files and loading the appropriate sounds. It uses some of the convenience routines available in parser.c.

• xml_theme.h
  • Contains the defninition of the XML tags, as well as the theme parsing routines.

The next few sections aim to provide a general idea of how the code is structured and make an introduction into the project easier. These sections will probably need to be refined over time, with detail added, so if you have any suggestions or pieces of crucial information you felt were missing, please send suggestions!