You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
arts/artsc/artsc.h

247 lines
8.1 KiB

/*
Copyright (C) 2000 Stefan Westerfeld
stefan@space.twc.de
This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Library General Public
License as published by the Free Software Foundation; either
version 2 of the License, or (at your option) any later version.
This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Library General Public License for more details.
You should have received a copy of the GNU Library General Public License
along with this library; see the file COPYING.LIB. If not, write to
the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
Boston, MA 02110-1301, USA.
*/
#ifndef ARTSC_H
#define ARTSC_H
#include "artsc_export.h"
#ifdef __cplusplus
extern "C" {
#endif
/**
* @libdoc aRts plain C API
*
* The aRts plain C API aims at easily writing/porting plain C apps to the
* arts sound server. What is provided is streaming functionality, in a
* blocking way. So for most apps, you simply remove the few system calls
* that deal with your audio device, and replace them with the appropriate
* arts calls.
*/
/**
* the type of streams (simply treat these as black boxes)
*/
typedef void *arts_stream_t;
/* error codes */
#define ARTS_E_NOSERVER ( -1 )
#define ARTS_E_NOBACKEND ( -2 )
#define ARTS_E_NOSTREAM ( -3 )
#define ARTS_E_NOINIT ( -4 )
#define ARTS_E_NOIMPL ( -5 )
/**
* the values for stream parameters
*
* @see arts_parameter_t
*/
enum arts_parameter_t_enum {
ARTS_P_BUFFER_SIZE = 1,
ARTS_P_BUFFER_TIME = 2,
ARTS_P_BUFFER_SPACE = 3,
ARTS_P_SERVER_LATENCY = 4,
ARTS_P_TOTAL_LATENCY = 5,
ARTS_P_BLOCKING = 6,
ARTS_P_PACKET_SIZE = 7,
ARTS_P_PACKET_COUNT = 8,
ARTS_P_PACKET_SETTINGS = 9
};
/**
* parameters for streams
*
* @li ARTS_P_BUFFER_SIZE (rw)
* The size of the internal buffers used for streaming to the server - this
* directly affects the latency that will occur. If you never set it
* explicitly, this value defaults to at least 65536 (64kb). Generally,
* it is important to know that the server itself gives some constraints
* which makes buffer sizes below a certain value impossible. So setting
* this parameter will always result in either getting what you wanted,
* or a larger streaming buffer due to server limitations.
*
* @li ARTS_P_BUFFER_TIME (rw)
* The time the buffer used for streaming to the server takes to play in
* milliseconds. This is just a more human readable method to set the buffer
* size, so setting ARTS_P_BUFFER_SIZE affects this parameter and the other
* way round. As aRts chooses reasonable buffer sizes for streaming (rather
* 3*16kb than 40234 bytes), setting this parameter will often end up with
* a slightly larger value than you requested.
*
* @li ARTS_P_BUFFER_SPACE (r)
* The amount of bytes that can be read/written without blocking (depending
* whether this is a record or play stream). As requesting this parameter
* does a few system calls (but no remote invocation) to verify that it is
* up-to-date, don't overuse it.
*
* @li ARTS_P_SERVER_LATENCY (r)
* The amount of latency the server creates (due to hardware buffering)
* in milliseconds.
*
* @li ARTS_P_TOTAL_LATENCY (r)
* The overall latency in milliseconds it takes (at most), from the time
* when you write a byte into a stream, until it gets played on the
* soundcard. This is simply a shortcut to the sum of ARTS_P_BUFFER_TIME
* and ARTS_P_SERVER_LATENCY.
*
* @li ARTS_P_BLOCKING (rw)
* If this parameter is 1 (the default), arts_read/arts_write will block
* when not all data can be read/written successfully, and wait until it
* works. If this parameter is 0, arts_read/arts_write will return
* the number of successfully read/written bytes immediately.
*
* @li ARTS_P_PACKET_SIZE (r)
* This returns the size of the packets used for buffering. The optimal
* size for arts_stream_write is always writing one packet. The buffering of
* streams works with audio packets. So the ARTS_P_BUFFER_SIZE parameter of
* streams (which specifies how many bytes of a stream are prebuffered),
* really consists of (ARTS_P_PACKET_SIZE) * (ARTS_P_PACKET_COUNT).
*
* @li ARTS_P_PACKET_COUNT (r)
* This returns the number of the packets are used for buffering. See
* ARTS_P_PACKET_SIZE for more.
*
* @li ARTS_P_PACKET_SETTINGS (rw)
* This is a way to configure packet size & packet count at the same time.
* The format is 0xCCCCSSSS, where 2^SSSS is the packet size, and CCCC is
* the packet count. Note that when writing this, you don't necessarily
* get the settings you requested.
*/
typedef enum arts_parameter_t_enum arts_parameter_t;
/**
* initializes the aRts C API, and connects to the sound server
*
* @return 0 if everything is all right, an error code otherwise
*/
ARTSC_EXPORT int arts_init(void);
/**
* disconnects from the sound server and frees the aRts C API internals
*/
ARTSC_EXPORT void arts_free(void);
/**
* asks aRtsd to free the DSP device and return 1 if it was successful,
* 0 if there were active non-suspendable modules
*/
ARTSC_EXPORT int arts_suspend(void);
/**
* asks aRtsd if the DSP device is free and return 1 if it is,
* 0 if not
*/
ARTSC_EXPORT int arts_suspended(void);
/**
* converts an error code to a human readable error message
*
* @param errorcode the errorcode (from another arts function that failed)
* @returns a text string with the error message
*/
ARTSC_EXPORT const char *arts_error_text(int errorcode);
/**
* open a stream for playing
*
* @param rate the sampling rate (something like 44100)
* @param bits how many bits each sample has (8 or 16)
* @param channels how many channels, 1 is mono, 2 is stereo
* @param name the name of the stream (these will be used so that the user can
* assign streams to effects/mixer channels and similar)
*
* @return a stream
*/
ARTSC_EXPORT arts_stream_t arts_play_stream(int rate, int bits, int channels, const char *name);
/**
* open a stream for recording
*
* @param rate the sampling rate (something like 44100)
* @param bits how many bits each sample has (8 or 16)
* @param channels how many channels, 1 is mono, 2 is stereo
* @param name the name of the stream (these will be used so that the user can
* assign streams to effects/mixer channels and similar)
*
* @return a stream
*/
ARTSC_EXPORT arts_stream_t arts_record_stream(int rate, int bits, int channels, const char *name);
/**
* close a stream
*/
ARTSC_EXPORT void arts_close_stream(arts_stream_t stream);
/**
* read samples from stream
*
* @param stream a previously opened record stream
* @param buffer a buffer with sample data
* @param count the number of bytes contained in the buffer
*
* @returns number of read bytes on success or error code
*/
ARTSC_EXPORT int arts_read(arts_stream_t stream, void *buffer, int count);
/**
* write samples to to stream
*
* @param stream a previously opened play stream
* @param buffer a buffer with sample data
* @param count the number of bytes contained in the buffer
*
* @returns number of written bytes on success or error code
*/
ARTSC_EXPORT int arts_write(arts_stream_t stream, const void *buffer, int count);
/**
* configure a parameter of a stream
*
* @param stream an opened record or play stream
* @param parameter the parameter you want to modify
* @param value the new value
*
* @returns the new value of the parameter (which may or may not be the value
* you wanted to have), or an error code if something went wrong
*/
ARTSC_EXPORT int arts_stream_set(arts_stream_t stream, arts_parameter_t param, int value);
/**
* query a parameter of a stream
*
* @param stream an opened record or play stream
* @param parameter the parameter you want to query
*
* @returns the value of the parameter, or an error code
*/
ARTSC_EXPORT int arts_stream_get(arts_stream_t stream, arts_parameter_t param);
#ifdef __cplusplus
}
#endif
#endif /* ARTSC_H */