From: Andre Noll Date: Fri, 21 Jul 2017 17:45:31 +0000 (+0200) Subject: Merge branch 'refs/heads/t/doxygen' X-Git-Tag: v0.6.1~52 X-Git-Url: http://git.tuebingen.mpg.de/?p=paraslash.git;a=commitdiff_plain;h=6811b2f8ea8b7a8c77046285c9432aee6327da80;hp=99b0bab8fcabc62aa154bc81da5b20ae9a3e3658 Merge branch 'refs/heads/t/doxygen' This series contains an update of Doxyfile to a newer doxygen version and an overhaul of the source code documentation. Several stale references have been fixed. Other parts of the documentation have been improved. Cooking for almost a month. * refs/heads/t/doxygen: aft.c: Trivial spelling/whitespace fixes. afh: Expand documentation of init function declarations. filter: Remove duplicate documentation of filter_get(). doxygen: Improve documentation of struct receiver. doxygen: Add \ref to references. Improve documentation of mm.c and mm.h. doxygen: Don't refer to Black Hats Manual. doxygen: Don't refer to libosl functions. doxygen: Trivial cleanups. doxygen: Remove some stale doxygen references. recv: Explain user data mechanism. Update to doxygen-1.8.11. The merge resulted in a few conflicts which were easy to resolve. --- diff --git a/NEWS.md b/NEWS.md index 60b94238..5398d3a5 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,6 +1,16 @@ NEWS ==== +------------------------------------------------ +0.6.1 (to be announced) "hyperbolic correlation" +------------------------------------------------ + +- The contents of overview.pdf have been integrated into the user + manual. +- The doxygen source browser has been disabled temporarily. The + API reference is still online, though. +- Overhaul of the source code documentation. + ------------------------------- 0.6.0 (2017-04-28) "fuzzy flux" ------------------------------- diff --git a/afh_common.c b/afh_common.c index 0d8d905c..1614c27c 100644 --- a/afh_common.c +++ b/afh_common.c @@ -16,6 +16,7 @@ #include "afh.h" typedef void afh_init_func(struct audio_format_handler *); + /* * Declaration of the audio format handler init functions. * @@ -26,7 +27,7 @@ typedef void afh_init_func(struct audio_format_handler *); * not all of these functions are defined. It does not hurt to declare them * anyway, and this avoids another set of ifdefs. */ -extern afh_init_func mp3_init, ogg_init, aac_afh_init, wma_afh_init, +extern afh_init_func mp3_afh_init, ogg_afh_init, aac_afh_init, wma_afh_init, spx_afh_init, flac_afh_init, opus_afh_init; /** The list of all status items */ @@ -37,7 +38,7 @@ const char *status_item_list[] = {STATUS_ITEM_ARRAY}; * * We always define the full array of audio formats even if some audio formats * were not compiled in. This is because for each audio file the number of its - * audio format is stored in the database. We don't want that numbers to become + * audio format is stored in the database. We don't want these numbers to become * stale just because the user installed a new version of paraslash that * supports a different set of audio formats. * @@ -47,12 +48,12 @@ const char *status_item_list[] = {STATUS_ITEM_ARRAY}; static struct audio_format_handler afl[] = { { .name = "mp3", - .init = mp3_init, + .init = mp3_afh_init, }, { .name = "ogg", #if defined(HAVE_OGG) && defined(HAVE_VORBIS) - .init = ogg_init, + .init = ogg_afh_init, #endif }, { diff --git a/afs.h b/afs.h index e113915c..ea4b497e 100644 --- a/afs.h +++ b/afs.h @@ -179,11 +179,9 @@ struct afs_callback_arg { typedef int afs_callback(struct afs_callback_arg *aca); /** - * Callbacks send chunks to data back to the command handler. Pointers to - * this type of function are used by \ref send_callback_request and friends - * to deal with the data in the command handler process. - * - * \sa \ref send_callback_request(). + * Some AFS callbacks need to send data back to the command handler. Pointers + * to this type of function are passed to \ref send_callback_request() and + * related functions to dispatch the data in the command handler process. */ typedef int callback_result_handler(struct osl_object *result, uint8_t band, void *private); int afs_cb_result_handler(struct osl_object *result, uint8_t band, void *private); diff --git a/aft.c b/aft.c index d58f9daf..c2642ed3 100644 --- a/aft.c +++ b/aft.c @@ -377,6 +377,7 @@ static void save_afhi(struct afh_info *afhi, char *buf) sprintf(p, "%s", afhi->tags.comment); } +/* does not load the chunk table */ static void load_afhi(const char *buf, struct afh_info *afhi) { afhi->seconds_total = read_u32(buf + AFHI_SECONDS_TOTAL_OFFSET); @@ -592,6 +593,10 @@ static int get_hash_of_row(const struct osl_row *row, unsigned char **hash) * \param afhi Result pointer. * * \return The return value of the underlying call to osl_get_object(). + * + * After the call the members of the afhi structure point to mapped memory + * which is owned by the osl table, Hence the caller must not attempt to free + * this memory by calling \ref clear_afhi(). */ int get_afhi_of_row(const struct osl_row *row, struct afh_info *afhi) { diff --git a/configure.ac b/configure.ac index a589613b..c2cb47e6 100644 --- a/configure.ac +++ b/configure.ac @@ -6,7 +6,6 @@ AC_CONFIG_HEADERS([config.h]) AC_CONFIG_FILES([Makefile]) AC_DEFUN([add_dot_o],[$(for i in $@; do printf "$i.o "; done)]) -AC_DEFUN([add_cmdline],[$(for i in $@; do printf "${i}.cmdline "; done)]) AC_DEFUN([LIB_ARG_WITH], [ AC_ARG_WITH($1-headers, [AS_HELP_STRING(--with-$1-headers=dir, [look for $1 headers in dir])]) @@ -76,7 +75,7 @@ STASH_FLAGS LIB_ARG_WITH([lopsub], [-llopsub]) HAVE_LOPSUB=yes AC_CHECK_HEADER(lopsub.h, [], [HAVE_LOPSUB=no]) -AC_CHECK_LIB([lopsub], [lls_merge], [], [HAVE_LOPSUB=yes]) +AC_CHECK_LIB([lopsub], [lls_merge], [], [HAVE_LOPSUB=no]) if test $HAVE_LOPSUB = no; then AC_MSG_ERROR([ The lopsub library is required to build this software, but the above checks indicate it is not installed on your system. @@ -197,7 +196,7 @@ AC_LINK_IFELSE([AC_LANG_PROGRAM([[ ]])],[have_ip_mreqn=yes],[have_ip_mreqn=no]) AC_MSG_RESULT($have_ip_mreqn) if test ${have_ip_mreqn} = yes; then - AC_DEFINE(HAVE_IP_MREQN, 1, define to 1 you have struct ip_mreqn) + AC_DEFINE(HAVE_IP_MREQN, 1, define to 1 if you have struct ip_mreqn) fi ########################################################################### ogg STASH_FLAGS diff --git a/error.h b/error.h index ea25f8cc..e5d2469b 100644 --- a/error.h +++ b/error.h @@ -8,6 +8,7 @@ /** Codes and messages. */ #define PARA_ERRORS \ + PARA_ERROR(SUCCESS, "success"), \ PARA_ERROR(AACDEC_INIT, "failed to init aac decoder"), \ PARA_ERROR(AAC_DECODE, "aac decode error"), \ PARA_ERROR(ACL_PERM, "access denied by acl"), \ diff --git a/grab_client.c b/grab_client.c index 11fff4cc..382b0470 100644 --- a/grab_client.c +++ b/grab_client.c @@ -8,7 +8,6 @@ #include #include -#include #include #include "audiod_cmd.lsg.h" diff --git a/gui.c b/gui.c index 24f1c727..5bad7e14 100644 --- a/gui.c +++ b/gui.c @@ -56,9 +56,7 @@ struct rb_entry { static struct ringbuffer *bot_win_rb; static unsigned scroll_position; - static pid_t exec_pid; - static int exec_fds[2] = {-1, -1}; static int loglevel; @@ -253,7 +251,7 @@ static char *km_keyname(int c) } /* Print given number of spaces to curses window. */ -static void add_spaces(WINDOW* win, unsigned int num) +static void add_spaces(WINDOW *win, unsigned int num) { const char space[] = " "; const unsigned sz = sizeof(space) - 1; /* number of spaces */ @@ -269,10 +267,10 @@ static void add_spaces(WINDOW* win, unsigned int num) } /* - * print aligned string to curses window. This function always prints + * Print aligned string to curses window. This function always prints * exactly len chars. */ -static int align_str(WINDOW* win, const char *str, unsigned int len, +static int align_str(WINDOW *win, const char *str, unsigned int len, unsigned int align) { int ret, num; /* of spaces */ @@ -458,10 +456,8 @@ static void rb_add_entry(int color, char *msg) waddstr(bot.win, msg); } -/* - * print formated output to bot win and refresh - */ -__printf_2_3 static void outputf(int color, const char* fmt,...) +/* Print formatted output to bot win and refresh. */ +__printf_2_3 static void outputf(int color, const char *fmt,...) { char *msg; va_list ap; @@ -504,8 +500,9 @@ static __printf_2_3 void curses_log(int ll, const char *fmt,...) vfprintf(stderr, fmt, ap); va_end(ap); } + /** The log function of para_gui, always set to curses_log(). */ -__printf_2_3 void (*para_log)(int, const char*, ...) = curses_log; +__printf_2_3 void (*para_log)(int, const char *, ...) = curses_log; /* Call endwin() to reset the terminal into non-visual mode. */ static void shutdown_curses(void) @@ -522,8 +519,8 @@ static void shutdown_curses(void) endwin(); } -/* disable curses, print a message, kill running processes and exit */ -__noreturn __printf_2_3 static void die(int exit_code, const char* fmt, ...) +/* Disable curses, print a message, kill running processes and exit. */ +__noreturn __printf_2_3 static void die(int exit_code, const char *fmt, ...) { va_list argp; @@ -546,9 +543,7 @@ __noreturn __printf_2_3 static void die(int exit_code, const char* fmt, ...) exit(exit_code); } -/* - * Print stat item #i to curses window - */ +/* Print stat item #i to curses window. */ static void print_stat_item(int i) { char *tmp; @@ -698,9 +693,7 @@ static int status_post_select(struct sched *s, void *context) return 0; } -/* - * init all windows - */ +/* Initialize all windows. */ static void init_wins(int top_lines) { int top_y = 0, bot_y = top_lines + 1, sb_y = LINES - 2, @@ -904,7 +897,7 @@ static void parse_config_file_or_die(bool reload) if (reload) /* config file overrides command line */ ret = lls(lls_merge(cf_lpr, cmdline_lpr, CMD_PTR, &merged_lpr, &errctx)); - else /* command line options overrride config file options */ + else /* command line options override config file options */ ret = lls(lls_merge(cmdline_lpr, cf_lpr, CMD_PTR, &merged_lpr, &errctx)); lls_free_parse_result(cf_lpr, CMD_PTR); @@ -928,7 +921,7 @@ free_cf: } } -/* reread configuration, terminate on errors */ +/* Reread configuration, terminate on errors. */ static void reread_conf(void) { /* @@ -942,9 +935,7 @@ static void reread_conf(void) print_in_bar(COLOR_MSG, "config file reloaded\n"); } -/* - * React to various signal-related events - */ +/* React to various signal-related events. */ static int signal_post_select(struct sched *s, __a_unused void *context) { int ret = para_next_signal(&s->rfds); @@ -1045,7 +1036,7 @@ static void input_pre_select(struct sched *s, __a_unused void *context) sched_min_delay(s); } -/* read from command pipe and print data to bot window */ +/* Read from command pipe and print data to bot window. */ static void exec_and_display(const char *file_and_args) { int ret, fds[3] = {0, 1, 1}; @@ -1079,9 +1070,7 @@ static void exec_para(const char *args) free(file_and_args); } -/* - * shutdown curses and stat pipe before executing external commands - */ +/* Shutdown curses and stat pipe before executing external commands. */ static void exec_external(char *file_and_args) { int fds[3] = {-1, -1, -1}; @@ -1135,7 +1124,8 @@ static void handle_command(int c) km_keyname(c)); } -static int input_post_select(__a_unused struct sched *s, __a_unused void *context) +static int input_post_select(__a_unused struct sched *s, + __a_unused void *context) { int ret; enum exec_status exs = exec_status(); diff --git a/mood.c b/mood.c index 92bef0fa..315ef0cb 100644 --- a/mood.c +++ b/mood.c @@ -140,8 +140,8 @@ static bool get_item_score(struct mood_item *item, const struct afs_info *afsi, } /* returns 1 if row admissible, 0 if not, negative on errors */ -static int compute_mood_score(const struct osl_row *aft_row, struct mood *m, - long *result) +static int row_is_admissible(const struct osl_row *aft_row, struct mood *m, + long *scorep) { struct mood_item *item; int ret; @@ -154,13 +154,13 @@ static int compute_mood_score(const struct osl_row *aft_row, struct mood *m, if (!m) return -E_NO_MOOD; ret = get_afsi_of_row(aft_row, &afsi); - if (ret< 0) + if (ret < 0) return ret; ret = get_afhi_of_row(aft_row, &afhi); - if (ret< 0) + if (ret < 0) return ret; ret = get_audio_file_path_of_row(aft_row, &path); - if (ret< 0) + if (ret < 0) return ret; /* reject audio file if it matches any entry in the deny list */ list_for_each_entry(item, &m->deny_list, mood_item_node) { @@ -190,7 +190,7 @@ static int compute_mood_score(const struct osl_row *aft_row, struct mood *m, } if (score_arg_sum) score /= score_arg_sum; - *result = score; + *scorep = score; return 1; } @@ -257,7 +257,6 @@ struct mood_line_parser_data { * is either an integer or "random" which assigns a random score to * all matching files */ - static int parse_mood_line(char *mood_line, void *data) { struct mood_line_parser_data *mlpd = data; @@ -566,7 +565,7 @@ static int add_if_admissible(struct osl_row *aft_row, void *data) int ret; long score = 0; - ret = compute_mood_score(aft_row, aa->m, &score); + ret = row_is_admissible(aft_row, aa->m, &score); if (ret <= 0) return ret; if (statistics.num >= aa->size) { @@ -625,7 +624,8 @@ _static_inline_ int64_t update_quadratic_deviation(int64_t n, int64_t old_qd, return old_qd + delta * (sigma - 2 * old_sum / n - delta / n); } -static int update_afs_statistics(struct afs_info *old_afsi, struct afs_info *new_afsi) +static int update_afs_statistics(struct afs_info *old_afsi, + struct afs_info *new_afsi) { unsigned n; int ret = get_num_admissible_files(&n); @@ -712,7 +712,7 @@ static int mood_update_audio_file(const struct osl_row *aft_row, if (ret < 0) return ret; was_admissible = ret; - ret = compute_mood_score(aft_row, current_mood, &score); + ret = row_is_admissible(aft_row, current_mood, &score); if (ret < 0) return ret; is_admissible = (ret > 0); @@ -846,6 +846,7 @@ out: free(aa.array); return ret; } + /* * Close and re-open the current mood. * diff --git a/mp3_afh.c b/mp3_afh.c index e5d0ff13..08837bec 100644 --- a/mp3_afh.c +++ b/mp3_afh.c @@ -690,7 +690,7 @@ static const char * const mp3_suffixes[] = {"mp3", NULL}; * * \param afh pointer to the struct to initialize */ -void mp3_init(struct audio_format_handler *afh) +void mp3_afh_init(struct audio_format_handler *afh) { afh->get_file_info = mp3_get_file_info; afh->suffixes = mp3_suffixes; diff --git a/ogg_afh.c b/ogg_afh.c index 2ddf0ee3..cb0611e0 100644 --- a/ogg_afh.c +++ b/ogg_afh.c @@ -212,7 +212,7 @@ static const char * const ogg_suffixes[] = {"ogg", NULL}; * * \param afh Pointer to the struct to initialize. */ -void ogg_init(struct audio_format_handler *afh) +void ogg_afh_init(struct audio_format_handler *afh) { afh->get_file_info = ogg_vorbis_get_file_info; afh->get_header = vorbis_get_header; diff --git a/play.c b/play.c index 7ffcd9ed..5fbf44c6 100644 --- a/play.c +++ b/play.c @@ -8,7 +8,6 @@ #include #include -#include #include #include "recv_cmd.lsg.h" @@ -109,8 +108,7 @@ struct play_task { char *afhi_txt; }; -typedef int (*play_cmd_handler_t)(struct play_task *pt, - struct lls_parse_result *lpr); +typedef int (*play_cmd_handler_t)(struct lls_parse_result *lpr); struct play_command_info { play_cmd_handler_t handler; }; @@ -127,7 +125,7 @@ INIT_STDERR_LOGGING(loglevel); char *stat_item_values[NUM_STAT_ITEMS] = {NULL}; static struct sched sched = {.max_fileno = 0}; -static struct play_task play_task; +static struct play_task play_task, *pt = &play_task; #define AFH_RECV_CMD (lls_cmd(LSG_RECV_CMD_CMD_AFH, recv_cmd_suite)) #define AFH_RECV ((struct receiver *)lls_user_data(AFH_RECV_CMD)) @@ -228,7 +226,7 @@ fail: exit(EXIT_FAILURE); } -static char get_playback_state(struct play_task *pt) +static char get_playback_state(void) { switch (pt->rq) { case CRT_NONE: return pt->playing? 'P' : 'U'; @@ -239,9 +237,9 @@ static char get_playback_state(struct play_task *pt) assert(false); }; -static long unsigned get_play_time(struct play_task *pt) +static long unsigned get_play_time(void) { - char state = get_playback_state(pt); + char state = get_playback_state(); long unsigned result; if (state != 'P' && state != 'U') @@ -263,7 +261,7 @@ static long unsigned get_play_time(struct play_task *pt) } -static void wipe_receiver_node(struct play_task *pt) +static void wipe_receiver_node(void) { PARA_NOTICE_LOG("cleaning up receiver node\n"); btr_remove_node(&pt->rn.btrn); @@ -273,7 +271,7 @@ static void wipe_receiver_node(struct play_task *pt) } /* returns: 0 not eof, 1: eof, < 0: fatal error. */ -static int get_playback_error(struct play_task *pt) +static int get_playback_error(void) { int err; @@ -292,13 +290,13 @@ static int get_playback_error(struct play_task *pt) return err; } -static int eof_cleanup(struct play_task *pt) +static int eof_cleanup(void) { const struct filter *decoder; const struct writer *w = writer_get(-1); /* default writer */ int ret; - ret = get_playback_error(pt); + ret = get_playback_error(); if (ret == 0) return ret; PARA_NOTICE_LOG("cleaning up wn/fn nodes\n"); @@ -324,7 +322,7 @@ static int eof_cleanup(struct play_task *pt) * paused. */ if (ret < 0) - wipe_receiver_node(pt); + wipe_receiver_node(); return ret; } @@ -352,7 +350,7 @@ static struct btr_node *new_recv_btrn(struct receiver_node *rn) .handler = AFH_RECV->execute)); } -static int open_new_file(struct play_task *pt) +static int open_new_file(void) { int ret; const char *path = get_playlist_file(pt->next_file); @@ -360,7 +358,7 @@ static int open_new_file(struct play_task *pt) char *argv[] = {"play", "-f", tmp, "-b", "0", NULL}; PARA_NOTICE_LOG("next file: %s\n", path); - wipe_receiver_node(pt); + wipe_receiver_node(); pt->start_chunk = 0; pt->rn.btrn = new_recv_btrn(&pt->rn); ret = lls(lls_parse(ARRAY_SIZE(argv) - 1, argv, AFH_RECV_CMD, @@ -400,11 +398,11 @@ static int open_new_file(struct play_task *pt) } return 1; fail: - wipe_receiver_node(pt); + wipe_receiver_node(); return ret; } -static int load_file(struct play_task *pt) +static int load_file(void) { const char *af; char *tmp, buf[20]; @@ -414,7 +412,7 @@ static int load_file(struct play_task *pt) btr_remove_node(&pt->rn.btrn); if (!pt->rn.receiver || pt->next_file != pt->current_file) { - ret = open_new_file(pt); + ret = open_new_file(); if (ret < 0) return ret; } else { @@ -468,11 +466,11 @@ static int load_file(struct play_task *pt) register_writer_node(&pt->wn, pt->fn.btrn, &sched); return 1; fail: - wipe_receiver_node(pt); + wipe_receiver_node(); return ret; } -static int next_valid_file(struct play_task *pt) +static int next_valid_file(void) { int i, j = pt->current_file; unsigned num_inputs = lls_num_inputs(play_lpr); @@ -485,20 +483,20 @@ static int next_valid_file(struct play_task *pt) return -E_NO_VALID_FILES; } -static int load_next_file(struct play_task *pt) +static int load_next_file(void) { int ret; again: if (pt->rq == CRT_NONE) { pt->start_chunk = 0; - ret = next_valid_file(pt); + ret = next_valid_file(); if (ret < 0) return ret; pt->next_file = ret; } else if (pt->rq == CRT_REPOS) pt->next_file = pt->current_file; - ret = load_file(pt); + ret = load_file(); if (ret < 0) { PARA_ERROR_LOG("%s: marking file as invalid\n", para_strerror(-ret)); @@ -511,7 +509,7 @@ again: return ret; } -static void kill_stream(struct play_task *pt) +static void kill_stream(void) { if (pt->wn.task) task_notify(pt->wn.task, E_EOF); @@ -520,7 +518,7 @@ static void kill_stream(struct play_task *pt) #ifdef HAVE_READLINE /* only called from com_prev(), nec. only if we have readline */ -static int previous_valid_file(struct play_task *pt) +static int previous_valid_file(void) { int i, j = pt->current_file; unsigned num_inputs = lls_num_inputs(play_lpr); @@ -729,7 +727,7 @@ static struct i9e_completer pp_completers[] = { {.name = NULL} }; -static void attach_stdout(struct play_task *pt, const char *name) +static void attach_stdout(const char *name) { if (pt->btrn) return; @@ -738,20 +736,19 @@ static void attach_stdout(struct play_task *pt, const char *name) i9e_attach_to_stdout(pt->btrn); } -static void detach_stdout(struct play_task *pt) +static void detach_stdout(void) { btr_remove_node(&pt->btrn); } -static int com_quit(struct play_task *pt, - __a_unused struct lls_parse_result *lpr) +static int com_quit(__a_unused struct lls_parse_result *lpr) { pt->rq = CRT_TERM_RQ; return 0; } EXPORT_PLAY_CMD_HANDLER(quit); -static int com_help(struct play_task *pt, struct lls_parse_result *lpr) +static int com_help(struct lls_parse_result *lpr) { int i, ret; char *buf, *errctx; @@ -804,8 +801,7 @@ static int com_help(struct play_task *pt, struct lls_parse_result *lpr) } EXPORT_PLAY_CMD_HANDLER(help); -static int com_info(struct play_task *pt, - __a_unused struct lls_parse_result *lpr) +static int com_info(__a_unused struct lls_parse_result *lpr) { char *buf; size_t sz; @@ -820,7 +816,7 @@ static int com_info(struct play_task *pt, } EXPORT_PLAY_CMD_HANDLER(info); -static void list_file(struct play_task *pt, int num) +static void list_file(int num) { char *buf; size_t sz; @@ -830,8 +826,7 @@ static void list_file(struct play_task *pt, int num) btr_add_output(buf, sz, pt->btrn); } -static int com_tasks(struct play_task *pt, - __a_unused struct lls_parse_result *lpr) +static int com_tasks(__a_unused struct lls_parse_result *lpr) { static char state; char *buf; @@ -839,26 +834,25 @@ static int com_tasks(struct play_task *pt, buf = get_task_list(&sched); btr_add_output(buf, strlen(buf), pt->btrn); - state = get_playback_state(pt); + state = get_playback_state(); sz = xasprintf(&buf, "state: %c\n", state); btr_add_output(buf, sz, pt->btrn); return 0; } EXPORT_PLAY_CMD_HANDLER(tasks); -static int com_ls(struct play_task *pt, - __a_unused struct lls_parse_result *lpr) +static int com_ls(__a_unused struct lls_parse_result *lpr) { int i; unsigned num_inputs = lls_num_inputs(play_lpr); for (i = 0; i < num_inputs; i++) - list_file(pt, i); + list_file(i); return 0; } EXPORT_PLAY_CMD_HANDLER(ls); -static int com_play(struct play_task *pt, struct lls_parse_result *lpr) +static int com_play(struct lls_parse_result *lpr) { int32_t x; int ret; @@ -871,7 +865,7 @@ static int com_play(struct play_task *pt, struct lls_parse_result *lpr) free(errctx); return ret; } - state = get_playback_state(pt); + state = get_playback_state(); if (lls_num_inputs(lpr) == 0) { if (state == 'P') return 0; @@ -885,24 +879,23 @@ static int com_play(struct play_task *pt, struct lls_parse_result *lpr) return ret; if (x < 0 || x >= lls_num_inputs(play_lpr)) return -ERRNO_TO_PARA_ERROR(EINVAL); - kill_stream(pt); + kill_stream(); pt->next_file = x; pt->rq = CRT_FILE_CHANGE; return 0; } EXPORT_PLAY_CMD_HANDLER(play); -static int com_pause(struct play_task *pt, - __a_unused struct lls_parse_result *lpr) +static int com_pause(__a_unused struct lls_parse_result *lpr) { char state; long unsigned seconds, ss; - state = get_playback_state(pt); + state = get_playback_state(); pt->playing = false; if (state != 'P') return 0; - seconds = get_play_time(pt); + seconds = get_play_time(); pt->playing = false; ss = 0; if (pt->seconds > 0) @@ -910,20 +903,19 @@ static int com_pause(struct play_task *pt, ss = PARA_MAX(ss, 0UL); ss = PARA_MIN(ss, pt->num_chunks); pt->start_chunk = ss; - kill_stream(pt); + kill_stream(); return 0; } EXPORT_PLAY_CMD_HANDLER(pause); -static int com_prev(struct play_task *pt, - __a_unused struct lls_parse_result *lpr) +static int com_prev(__a_unused struct lls_parse_result *lpr) { int ret; - ret = previous_valid_file(pt); + ret = previous_valid_file(); if (ret < 0) return ret; - kill_stream(pt); + kill_stream(); pt->next_file = ret; pt->rq = CRT_FILE_CHANGE; pt->start_chunk = 0; @@ -931,15 +923,14 @@ static int com_prev(struct play_task *pt, } EXPORT_PLAY_CMD_HANDLER(prev); -static int com_next(struct play_task *pt, - __a_unused struct lls_parse_result *lpr) +static int com_next(__a_unused struct lls_parse_result *lpr) { int ret; - ret = next_valid_file(pt); + ret = next_valid_file(); if (ret < 0) return ret; - kill_stream(pt); + kill_stream(); pt->next_file = ret; pt->rq = CRT_FILE_CHANGE; pt->start_chunk = 0; @@ -947,23 +938,21 @@ static int com_next(struct play_task *pt, } EXPORT_PLAY_CMD_HANDLER(next); -static int com_fg(struct play_task *pt, - __a_unused struct lls_parse_result *lpr) +static int com_fg(__a_unused struct lls_parse_result *lpr) { pt->background = false; return 0; } EXPORT_PLAY_CMD_HANDLER(fg); -static int com_bg(struct play_task *pt, - __a_unused struct lls_parse_result *lpr) +static int com_bg(__a_unused struct lls_parse_result *lpr) { pt->background = true; return 0; } EXPORT_PLAY_CMD_HANDLER(bg); -static int com_jmp(struct play_task *pt, struct lls_parse_result *lpr) +static int com_jmp(struct lls_parse_result *lpr) { int32_t percent; int ret; @@ -982,19 +971,19 @@ static int com_jmp(struct play_task *pt, struct lls_parse_result *lpr) if (percent < 0 || percent > 100) return -ERRNO_TO_PARA_ERROR(EINVAL); if (percent == 100) - return com_next(pt, NULL); + return com_next(NULL); if (pt->playing && !pt->fn.btrn) return 0; pt->start_chunk = percent * pt->num_chunks / 100; if (!pt->playing) return 0; pt->rq = CRT_REPOS; - kill_stream(pt); + kill_stream(); return 0; } EXPORT_PLAY_CMD_HANDLER(jmp); -static int com_ff(struct play_task *pt, struct lls_parse_result *lpr) +static int com_ff(struct lls_parse_result *lpr) { int32_t seconds; char *errctx; @@ -1012,7 +1001,7 @@ static int com_ff(struct play_task *pt, struct lls_parse_result *lpr) return ret; if (pt->playing && !pt->fn.btrn) return 0; - seconds += get_play_time(pt); + seconds += get_play_time(); seconds = PARA_MIN(seconds, (typeof(seconds))pt->seconds - 4); seconds = PARA_MAX(seconds, 0); pt->start_chunk = pt->num_chunks * seconds / pt->seconds; @@ -1021,12 +1010,12 @@ static int com_ff(struct play_task *pt, struct lls_parse_result *lpr) if (!pt->playing) return 0; pt->rq = CRT_REPOS; - kill_stream(pt); + kill_stream(); return 0; } EXPORT_PLAY_CMD_HANDLER(ff); -static int run_command(char *line, struct play_task *pt) +static int run_command(char *line) { int ret, argc; char **argv = NULL; @@ -1035,7 +1024,7 @@ static int run_command(char *line, struct play_task *pt) struct lls_parse_result *lpr; const struct lls_command *cmd; - attach_stdout(pt, __FUNCTION__); + attach_stdout(__FUNCTION__); ret = create_argv(line, " ", &argv); if (ret < 0) goto out; @@ -1050,7 +1039,7 @@ static int run_command(char *line, struct play_task *pt) if (ret < 0) goto out; pci = lls_user_data(cmd); - ret = pci->handler(pt, lpr); + ret = pci->handler(lpr); lls_free_parse_result(lpr, cmd); out: if (errctx) @@ -1062,12 +1051,11 @@ out: static int play_i9e_line_handler(char *line) { - return run_command(line, &play_task); + return run_command(line); } static int play_i9e_key_handler(int key) { - struct play_task *pt = &play_task; int idx = get_key_map_idx(key); char *seq = get_key_map_seq(key); char *cmd = get_key_map_cmd(key); @@ -1076,7 +1064,7 @@ static int play_i9e_key_handler(int key) PARA_NOTICE_LOG("pressed %d: %s key #%d (%s -> %s)\n", key, internal? "internal" : "user-defined", idx, seq, cmd); - run_command(cmd, pt); + run_command(cmd); free(seq); free(cmd); pt->next_update = *now; @@ -1093,7 +1081,7 @@ static struct i9e_client_info ici = { static void sigint_handler(int sig) { - play_task.background = true; + pt->background = true; i9e_signal_dispatch(sig); } @@ -1102,7 +1090,7 @@ static void sigint_handler(int sig) * stderr. Once the i9e subsystem has been initialized, we switch to the i9e * log facility. */ -static void session_open(struct play_task *pt) +static void session_open(void) { int ret; char *history_file; @@ -1146,7 +1134,7 @@ out: exit(EXIT_FAILURE); } -static void session_update_time_string(struct play_task *pt, char *str, unsigned len) +static void session_update_time_string(char *str, unsigned len) { if (pt->background) return; @@ -1171,30 +1159,30 @@ static void session_update_time_string(struct play_task *pt, char *str, unsigned * terminates. Subsequent calls to i9e_get_error() then return negative and we * are allowed to call i9e_close() and terminate as well. */ -static int session_post_select(__a_unused struct sched *s, struct play_task *pt) +static int session_post_select(__a_unused struct sched *s) { int ret; if (pt->background) - detach_stdout(pt); + detach_stdout(); else - attach_stdout(pt, __FUNCTION__); + attach_stdout(__FUNCTION__); ret = i9e_get_error(); if (ret < 0) { - kill_stream(pt); + kill_stream(); i9e_close(); para_log = stderr_log; free(ici.history_file); return ret; } - if (get_playback_state(pt) == 'X') + if (get_playback_state() == 'X') i9e_signal_dispatch(SIGTERM); return 0; } #else /* HAVE_READLINE */ -static int session_post_select(struct sched *s, struct play_task *pt) +static int session_post_select(struct sched *s) { char c; @@ -1202,38 +1190,36 @@ static int session_post_select(struct sched *s, struct play_task *pt) return 0; if (read(STDIN_FILENO, &c, 1)) do_nothing; - kill_stream(pt); + kill_stream(); return 1; } -static void session_open(__a_unused struct play_task *pt) +static void session_open(void) { } -static void session_update_time_string(__a_unused struct play_task *pt, - char *str, __a_unused unsigned len) +static void session_update_time_string(char *str, __a_unused unsigned len) { printf("\r%s ", str); fflush(stdout); } #endif /* HAVE_READLINE */ -static void play_pre_select(struct sched *s, void *context) +static void play_pre_select(struct sched *s, __a_unused void *context) { - struct play_task *pt = context; char state; para_fd_set(STDIN_FILENO, &s->rfds, &s->max_fileno); - state = get_playback_state(pt); + state = get_playback_state(); if (state == 'R' || state == 'F' || state == 'X') return sched_min_delay(s); sched_request_barrier_or_min_delay(&pt->next_update, s); } -static unsigned get_time_string(struct play_task *pt, char **result) +static unsigned get_time_string(char **result) { int seconds, length; - char state = get_playback_state(pt); + char state = get_playback_state(); /* do not return anything if things are about to change */ if (state != 'P' && state != 'U') { @@ -1243,7 +1229,7 @@ static unsigned get_time_string(struct play_task *pt, char **result) length = pt->seconds; if (length == 0) return xasprintf(result, "0:00 [0:00] (0%%/0:00)"); - seconds = get_play_time(pt); + seconds = get_play_time(); return xasprintf(result, "#%u: %d:%02d [%d:%02d] (%d%%/%d:%02d) %s", pt->current_file, seconds / 60, @@ -1257,24 +1243,23 @@ static unsigned get_time_string(struct play_task *pt, char **result) ); } -static int play_post_select(struct sched *s, void *context) +static int play_post_select(struct sched *s, __a_unused void *context) { - struct play_task *pt = context; int ret; - ret = eof_cleanup(pt); + ret = eof_cleanup(); if (ret < 0) { pt->rq = CRT_TERM_RQ; return 0; } - ret = session_post_select(s, pt); + ret = session_post_select(s); if (ret < 0) goto out; if (!pt->wn.btrn && !pt->fn.btrn) { - char state = get_playback_state(pt); + char state = get_playback_state(); if (state == 'P' || state == 'R' || state == 'F') { PARA_NOTICE_LOG("state: %c\n", state); - ret = load_next_file(pt); + ret = load_next_file(); if (ret < 0) { PARA_ERROR_LOG("%s\n", para_strerror(-ret)); pt->rq = CRT_TERM_RQ; @@ -1286,10 +1271,10 @@ static int play_post_select(struct sched *s, void *context) } if (tv_diff(now, &pt->next_update, NULL) >= 0) { char *str; - unsigned len = get_time_string(pt, &str); + unsigned len = get_time_string(&str); struct timeval delay = {.tv_sec = 0, .tv_usec = 100 * 1000}; if (str && len > 0) - session_update_time_string(pt, str, len); + session_update_time_string(str, len); free(str); tv_add(now, &delay, &pt->next_update); } @@ -1309,7 +1294,6 @@ out: int main(int argc, char *argv[]) { int ret; - struct play_task *pt = &play_task; unsigned num_inputs; /* needed this early to make help work */ @@ -1318,7 +1302,7 @@ int main(int argc, char *argv[]) sched.default_timeout.tv_sec = 5; parse_config_or_die(argc, argv); AFH_RECV->init(); - session_open(pt); + session_open(); num_inputs = lls_num_inputs(play_lpr); init_shuffle_map(); pt->invalid = para_calloc(sizeof(*pt->invalid) * num_inputs); diff --git a/recv.c b/recv.c index 9842c7dc..26aa7fd7 100644 --- a/recv.c +++ b/recv.c @@ -8,7 +8,6 @@ #include #include -#include #include #include "recv_cmd.lsg.h" diff --git a/string.c b/string.c index 5eb1606e..e675502c 100644 --- a/string.c +++ b/string.c @@ -10,7 +10,6 @@ #include #include /* uname() */ -#include #include #include #include diff --git a/web/dia/overview.dia b/web/dia/overview.dia deleted file mode 100644 index f9e01586..00000000 --- a/web/dia/overview.dia +++ /dev/null @@ -1,3817 +0,0 @@ - - - - - - - - - - - - - #A4# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - #Overview# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - #para_server# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - #Incoming connections arrive via TCP at the dispatcher which creates a -command handler process for each connection. - -After the connecting client has been authenticated, the command -handler propagates the incoming request either to the audio file -selector (afs) or to the virtual streaming system (vss). Results are sent -back to the client. - -afs maintans the audio file database and is responsible for selecting -and loading audio files while vss controls the paraslash senders. When -vss needs to stream an audio file it requests an open file descriptor from -afs and feeds small chunks of data (e.g. mp3 frames) to the senders -which send the chunks to all connected clients.# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - ## - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - ## - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - #dispatcher# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - #senders# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - #vss# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - #command -handler# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - #afs# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - ## - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - #para_server# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - #para_audiod# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - #para_audioc# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - #para_gui# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - #para_client# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - ## - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - ## - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - ## - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - ## - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - #The two main applications of the paraslash suite (shaded green) are -para_server and para_audiod. Both run in the background usually. -para_server maintains the audio file database and acts as the streaming -source, while para_audiod is the streaming client. - -The two client programs, para_client and para_audioc communicate -with para_server and para_audiod, respectively. - -para_gui controls para_server/audiod by executing paraslash commands. -Command output is shown in a curses window. para_gui automatically -executes para_audioc to obtain the state of para_audiod and para_server -and the metadata of the current audio file. - -Network connections are shaded grey, local connections black.# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - #para_audiod# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - #The purpose of para_audiod is to download, decode and play an audio -stream received from para_server. It fetches the para_server status and -starts a suitable buffer tree (shaded blue) if an audio stream is available. - -The buffer tree usually consists of a receiver, any number of filters and -a writer. The receiver downloads the audio stream from para_server and -the filters decode or modify the received data. The writer plays the -decoded stream. - -The dispatcher acts on (local) requests from para_audioc, for example to -dump information about the current audio file.# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - #The audio file selector (afs) accepts two different kinds of incoming -connections: A bidirectional pipe shared with para_server is used for -passing the file descriptor of the current audio file to the server -process. The local socket is used by command handlers which query -or update the database. - -To add a new file to the database, afs opens the file and locates an -audio format handler (afh) that recognizes the file. A new database -entry with metadata obtained from the afh is then added to the -database.# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - #The audio file selector# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - #audio files# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - #para_server# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - #afh# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - #osl db# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - #command handler# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - #afs# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - #The OSL database# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - #Metadata about all known audio files is stored in serveral tables of a -database which is driven by libosl, the object storage layer library. - -The "audio files" table is the main table of the database. It contains -path, hash and metadata of each known file. - -The "attributes" table maps each of the 64 possible attributes to a -string. The attribute value of the file's metadata is translated through -this table. - -The tables shown shaded are blob tables which support add, rm, mv, -cat, ls commands. All of these are optional. - -The "score" table describes the subset of admissible files for the -current playlist or mood. This table is created on demand, resides -only in memory and is discarded on exit. - -When the next audio file is to be streamed, the audio file selector gets -the entry with the highest score from the "score" table, obtains path, -hash, and metadata for this entry from the "audio files" table, opens -the path and verifies the hash.# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - #audio files# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - #playlists# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - #images# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - #attributes# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - #lyrics# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - #moods# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - #score# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - #dispatcher# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - #status fetcher# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - #para_server# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - #receiver# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - #filter1# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - #filter 2# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - #writer# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - #para_audioc# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/web/documentation.in.html b/web/documentation.in.html index 9e8b59ce..d6d690a1 100644 --- a/web/documentation.in.html +++ b/web/documentation.in.html @@ -5,12 +5,6 @@

General information

    -
  • overview.pdf, - - a pdf file containing a sketch which illustrates how - the pieces of paraslash work together. - -
  • user manual, Installation, Configuration and Usage.
    • diff --git a/web/manual.md b/web/manual.md index 5216c6b5..96d724c9 100644 --- a/web/manual.md +++ b/web/manual.md @@ -12,81 +12,143 @@ paraslash executable. Introduction ============ -In this chapter we give an [overview](#Overview) of the interactions of -the two main programs contained in the paraslash package, followed by +In this chapter we give an [overview](#Overview) of the interactions +of the programs contained in the paraslash package, followed by [brief descriptions](#The.paraslash.executables) of all executables. Overview -------- The core functionality of the para suite is provided by two main -executables, para_server and para_audiod. The former maintains a -database of audio files and streams these files to para_audiod which -receives and plays the stream. - -In a typical setting, both para_server and para_audiod act as -background daemons whose functionality is controlled by client -programs: the para_audioc client controls para_audiod over a local -socket while the para_client program connects to para_server over a -local or remote networking connection. - -Typically, these two daemons run on different hosts but a local setup -is also possible. +applications, para_server and para_audiod. para_server maintains +the audio file database and acts as the streaming source, while +para_audiod is the streaming client. Usually, both run in the +background on different hosts but a local setup is also possible. A simplified picture of a typical setup is as follows - server_host client_host - ~~~~~~~~~~~ ~~~~~~~~~~~ - +-----------+ audio stream +-----------+ - |para_server| -----------------------------> |para_audiod| - +-----------+ +-----------+ - ^ ^ - | | - | | connect - | | - | | - | +-----------+ - | |para_audioc| - | +-----------+ - | - | - | connect +-----------+ - +-------------------------------------- |para_client| - +-----------+ + .____________________. + | ______ | + .-----------------------. | .d########b. | + |.---------------------.| | .d############b | + || || | .d######""####//b. | + || || | 9######( )######P | + || || | 'b######++######d' | + || Screen || | "9############P" | + || || | "9a########P" | + || || | `""""'' | + |`---------------------'| | ________________ | + `-----------------------' | |________________| | + ___) (___ |____________________| + `-._______.-' loudspeaker + | | + | | + | | + .____/ \___. ._____________. ._____/ \_____. + | | | | | | + | para_gui |-----| para_audioc |-----| para_audiod | + |____ ___| |_____________| |_____ _____| + \ / \ / + | | + | | + | | + ._____/ \_____. ._____/ \_____. + | | | | + | para_client |-----------------------| para_server | + |_____________| |_____ _____| + \ / + | + | + .-'"""`-. + ( ) + |`-.___.-'| + | | + |. ' " ` .| + | | + `-.___.-' + Database + +The two client programs, para_client and para_audioc communicate with +para_server and para_audiod, respectively. + +para_gui controls para_server and para_audiod by executing para_client +and para_audioc. In particular, it runs a command to obtain the state +of para_audiod and para_server, and the metadata of the current audio +file. This information is pretty-printed in a curses window. + The paraslash executables ------------------------- -### para_server ### +

    para_server

    para_server streams binary audio data (MP3, ...) over local and/or remote networks. It listens on a TCP port and accepts commands such -as play, stop, pause, next from authenticated clients. There are -many more commands though, see the man page of para_server for a -description of all commands. - -It supports three built-in network streaming protocols -(senders/receivers): HTTP, DCCP, or UDP. This is explained in more -detail in the section on [networking](#Networking). - -The built-in audio file selector of paraslash is used to manage your -audio files. It maintains statistics on the usage of all available -audio files such as last-played time, and the number of times each -file was selected. - -Additional information may be added to the database to allow +as play, stop, pause, next from authenticated clients. The components +of para_server are illustrated in the following diagram: + + ______________________________________________________________________ network + | | | | | + | .-'""""`-. | | | | + | ( ) | | | | + .____/ \_____. |`-.____.-'| .____/ \____/ \____/ \____. | + | | | | | | | + | dispatcher | | database | | senders (http/udp/dccp) | | + |____ _____| | | |___________ ___________| | + \ / |. ' "" ` .| \ / | + | | | | | + | `-.____.-' | | + | | | | + | | | | + | | | | + | ._____/ \_____. .________/ \________. | + | | | | | | + | | audio file |________| virtual streaming | | + | | selector | | system | | + | |_____ _____| |________ ________| | + | \ / \ / | + | | | | + | | | | + | | ._________________. | | + | | | | | | + | `---| command handler |---' | + | |____ ___ ____| | + | \ / \ / | + | | | | + | | | | + | | | | + `-------------------------' `--------------------------' + + +Incoming connections arrive at the dispatcher which creates a process +dedicated to the connection. Its task is to authenticate the client +and to run the command handler which forwards the client request to +either the audio file selector or the virtual streaming system. Results +(if any) are sent back to the client. + +The audio file selector manages audio files using various database +tables. It maintains statistics on the usage of all audio files such as +last-played time and the number of times each file was selected. It +is also responsible for selecting and loading audio files for +streaming. Additional information may be added to the database to allow fine-grained selection based on various properties of the audio file, -including information found in (ID3) tags. However, old-fashioned -playlists are also supported. - -It is also possible to store images (album covers) and lyrics in the -database and associate these to the corresponding audio files. - +including information found in (ID3) tags. Simple playlists are also +supported. It is possible to store images (album covers) and lyrics +in the database and associate these to the corresponding audio files. The section on the [audio file selector](#The.audio.file.selector) -discusses this topic. +discusses this topic in more detail. + +Another component of para_server is the virtual streaming system, +which controls the paraslash senders. During streaming it requests +small chunks of data (e.g., mp3 frames) from the audio file selector +and feeds them to the senders which forward the chunks to connected +clients. +The three senders of para_server correspond to network streaming +protocols based on HTTP, DCCP, or UDP. This is explained in the +section on [networking](#Networking). -### para_client ### +

    para_client

    The client program to connect to para_server. paraslash commands are sent to para_server and the response is dumped to STDOUT. This @@ -101,29 +163,67 @@ If para_client is started without non-option arguments, an interactive session (shell) is started. Command history and command completion are supported through libreadline. -### para_audiod ### - -The local daemon that collects information from para_server. - -It runs on the client side and connects to para_server. As soon as -para_server announces the availability of an audio stream, para_audiod -starts an appropriate receiver, any number of filters and a paraslash -writer to play the stream. - -Moreover, para_audiod listens on a local socket and sends status -information about para_server and para_audiod to local clients on -request. Access via this local socket may be restricted by using Unix -socket credentials, if available. - - -### para_audioc ### +

    para_audiod

    + +The purpose of para_audiod is to download, decode and play an audio +stream received from para_server. A typical setup looks as follows. + + + .----------------------------. + | | + | | + ._____/ \_____. .___/ \____. + | | .----------| | + | para_server | | .______| receiver | + |_____ ____| | | |___ ____| + \ / | | \ / + | | | | + | | | | + | | | | + ._____/ \_____. | | .___/ \____. + | | | | | | + | status task |-----+ | | filter 1 | + |_____________| | |___ ____| + | \ / + | | .____________________. + | | | ______ | + .____________. | .___/ \____. | .d########b. | + | | | | | | .d############b | + | dispatcher |----------' | filter 2 | | .d######""####//b. | + |_____ ____| |___ ____| | 9######( )######P | + \ / \ / | 'b######++######d' | + | | | "9############P" | + | | | "9a########P" | + ._____/ \_____. .___/ \____. | `""""'' | + | | | | | ________________ | + | para_audioc | | writer |------| |________________| | + |_____________| |__________| |____________________| + + +The status task of para_audiod connects to para_server and runs the +"stat" command to retrieve the current server status. If an audio +stream is available, para_audiod starts a so-called buffer tree to +play the stream. + +The buffer tree consists of a receiver, any number of filters and a +writer. The receiver downloads the audio stream from para_server and +the filters decode or modify the received data. The writer plays the +decoded stream. + +The dispatcher of para_audiod listens on a local socket and runs +audiod commands on behalf of para_audioc. For example, para_gui runs +para_audioc to obtain status information about para_audiod and the +current audio file. Access to the local socket may be restricted by +means of Unix socket credentials. + +

    para_audioc

    The client program which talks to para_audiod. Used to control para_audiod, to receive status info, or to grab the stream at any point of the decoding process. Like para_client, para_audioc supports interactive sessions on systems with libreadline. -### para_recv ### +

    para_recv

    A command line HTTP/DCCP/UDP stream grabber. The http mode is compatible with arbitrary HTTP streaming sources (e.g. icecast). @@ -134,7 +234,7 @@ optionally 'just in time'. This allows to cut an audio file without first decoding it, and it enables third-party software which is unaware of the particular audio format to send complete frames in real time. -### para_filter ### +

    para_filter

    A filter program that reads from STDIN and writes to STDOUT. Like para_recv, this is an atomic building block which can be used to @@ -143,30 +243,33 @@ different functionalities in one tool: decoders for multiple audio formats and a number of processing filters, among these a normalizer for audio volume. -### para_afh ### +

    para_afh

    A small stand-alone program that prints tech info about the given audio file to STDOUT. It can be instructed to print a "chunk table", an array of offsets within the audio file. -### para_write ### +

    para_write

    A modular audio stream writer. It supports a simple file writer output plug-in and optional WAV/raw players for ALSA (Linux) and OSS. para_write can also be used as a stand-alone WAV or raw audio player. -### para_play ### +

    para_play

    -A command line audio player. +A command line audio player which supports the same audio formats as +para_server. It differs from other players in that it has an insert +and a command mode, like the vi editor. Line editing is based on +libreadline, and tab completion and command history are supported. -### para_gui ### +

    para_gui

    Curses-based gui that presents status information obtained in a curses window. Appearance can be customized via themes. para_gui provides key-bindings for the most common server commands and new key-bindings can be added easily. -### para_mixer ### +

    para_mixer

    An alarm clock and volume-fader for OSS and ALSA. @@ -182,8 +285,10 @@ source code and the steps that have to be performed in order to Requirements ------------ -### For the impatient ### +

    For the impatient

    + git clone git://git.tuebingen.mpg.de/lopsub + cd lopsub && make && sudo make install git clone git://git.tuebingen.mpg.de/osl cd osl && make && sudo make install && sudo ldconfig sudo apt-get install autoconf libssl-dev m4 \ @@ -192,16 +297,10 @@ Requirements libasound2-dev libao-dev libreadline-dev libncurses-dev \ libopus-dev -### Detailed description ### +

    Detailed description

    In any case you will need -- [libosl](http://people.tuebingen.mpg.de/maan/osl/). The _object -storage layer_ library is used by para_server. To clone the source -code repository, execute - - git clone git://git.tuebingen.mpg.de/osl - - [lopsub](http://people.tuebingen.mpg.de/maan/lopsub/). The long option parser for subcommands generates the command line and config file parsers for all paraslash executables. Clone the source code @@ -225,6 +324,12 @@ from templates by the m4 macro processor. Optional: +- [libosl](http://people.tuebingen.mpg.de/maan/osl/). The _object +storage layer_ library is used by para_server. To clone the source +code repository, execute + + git clone git://git.tuebingen.mpg.de/osl + - [openssl](http://www.openssl.org/) or [libgcrypt](ftp://ftp.gnupg.org/gcrypt/libgcrypt/). At least one of these two libraries is needed as the backend for cryptographic @@ -311,7 +416,7 @@ to install executables under /usr/local/bin and the man pages under Configuration ------------- -### Create a paraslash user ### +

    Create a paraslash user

    In order to control para_server at runtime you must create a paraslash user. As authentication is based on the RSA crypto system you'll have @@ -355,7 +460,7 @@ Finally, tell para_client to connect to server_host: echo 'hostname server_host' > $conf -### Start para_server ### +

    Start para_server

    For this first try, we'll use the info loglevel to make the output of para_server more verbose. @@ -371,7 +476,7 @@ commands. Open a new shell as bar@client_host and try to retrieve the list of available commands and some server info. Don't proceed if this doesn't work. -### Create and populate the database ### +

    Create and populate the database

    An empty database is created with @@ -399,7 +504,7 @@ You may print the list of all known audio files with para_client ls -### Configure para_audiod ### +

    Configure para_audiod

    We will have to tell para_audiod that it should receive the audio stream from server_host via http: @@ -420,14 +525,6 @@ in which order. Troubleshooting --------------- -If you receive a socket related error on server or audiod startup, -make sure you have write permissions to the /var/paraslash directory: - - sudo chown $LOGNAME /var/paraslash - -Alternatively, use the --afs-socket (para_server) or --socket -(para_audiod) option to specify a different socket pathname. - To identify streaming problems try to receive, decode and play the stream manually using para_recv, para_filter and para_write as follows. For simplicity we assume that you're running Linux/ALSA and that only @@ -569,8 +666,7 @@ execute. The output of para_client help -contains in the third column the permissions needed to execute the -command. +contains the permissions needed to execute the command. It is possible to make para_server reread the user_list file by executing the paraslash "hup" command or by sending SIGHUP to the @@ -596,27 +692,21 @@ The audio file selector paraslash comes with a sophisticated audio file selector (AFS), whose main task is to determine which file to stream next, based on information on the audio files stored in a database. It communicates -also with para_client whenever an AFS command is executed, for example -to answer a database query. +also with para_client via the command handler whenever an AFS command +is executed, for example to answer a database query. -Besides the traditional playlists, AFS supports audio file selection +Besides the simple playlists, AFS supports audio file selection based on _moods_ which act as a filter that limits the set of all -known audio files to those which satisfy certain criteria. It also +known audio files to those which satisfy certain criteria. It also maintains tables containing images (e.g. album cover art) and lyrics that can be associated with one or more audio files. -AFS employs [libosl](http://people.tuebingen.mpg.de/maan/osl/), the -object storage layer library, as the backend library for storing -information on audio files, playlists, etc. This library offers -functionality similar to a relational database, but is much more -lightweight than a full database backend. - In this chapter we sketch the setup of the [AFS process](#The.AFS.process) during server startup and proceed with the description of the [layout](#Database.layout) of the various database tables. The section on [playlists and moods](#Playlists.and.moods) explains these two audio file selection mechanisms in detail -and contains pratical examples. The way [file renames and content +and contains practical examples. The way [file renames and content changes](#File.renames.and.content.changes) are detected is discussed briefly before the [Troubleshooting](#Troubleshooting) section concludes the chapter. @@ -625,25 +715,85 @@ The AFS process --------------- On startup, para_server forks to create the AFS process which opens -the OSL database tables. The server process communicates with the -AFS process via pipes and shared memory. Usually, the AFS process -awakes only briefly whenever the current audio file changes. The AFS -process determines the next audio file, opens it, verifies it has -not been changed since it was added to the database and passes the -open file descriptor to the server process, along with audio file -meta-data such as file name, duration, audio format and so on. The -server process then starts to stream the audio file. - -The AFS process also accepts connections from local clients via -a well-known socket. However, only child processes of para_server -may connect through this socket. All server commands that have the -AFS_READ or AFS_WRITE permission bits use this mechanism to query or -change the database. +the database tables. The AFS process accepts incoming connections +which arrive either on a pipe which is shared with para_server, +or on the local socket it is listening on. The setup is as follows. + + .___________________. .______________. + | | | | + | virtual streaming | | audio format | + | system | | handler | + |_________ _______| |_____ ______| + \ / \ / + | | + .-'""""`-. | | .-'""""`-. + ( ) | | ( ) + |`-.____.-'| .__/ \________________/ \___. |`-.____.-'| + | | | | | | + | file |----| AFS (audio file selector) |----| OSL | + | system | | process | | database | + | | |___________________________| | | + |. ' "" ` .| | |. ' "" ` .| + | | | | | + `-.____.-' | `-.____.-' + ._______/ \_______. + | | + | command handler | + |_______ _______| + \ / + | + | + | + ._____/ \_____. + | | + | para_client | + |_____________| + +The virtual streaming system, which is part of the server process, +communicates with the AFS process via pipes and shared memory. When +the current audio file changes, it sends a notification through the +shared pipe. The AFS process queries the database to determine the +next audio file, opens it, verifies that it has not been changed since +it was added to the database and passes the open file descriptor back +to the virtual streaming system, along with audio file meta-data such +as file name, duration, audio format and so on. The virtual streaming +system then starts to stream the file. + +The command handlers of all AFS server commands use the local socket +to query or update the database. For example, the command handler of +the add command sends the path of an audio file to the local socket. +The AFS process opens the file and tries to find an audio format +handler which recognizes the file. If all goes well, a new database +entry with metadata obtained from the audio format handler is added +to the database. + +Note that AFS employs +[libosl](http://people.tuebingen.mpg.de/maan/osl/), the object +storage layer library, as the database backend. This library offers +functionality similar to a relational database, but is much more +lightweight than a full featured database management system. Database layout --------------- -### The audio file table ### +Metadata about the known audio files is stored in an OSL database. This +database consists of the following tables: + +- The audio file table contains path, hash and metadata of each +known file. + +- The "attributes" table maps each of the 64 possible attributes to a +string. + +- The "blob" tables store images, lyrics, moods, playlists. All of +these are optional. + +- The "score" table describes the subset of admissible files for the +current playlist or mood. + +All tables are described in more detail below. + +

    The audio file table

    This is the most important and usually also the largest table of the AFS database. It contains the information needed to stream each audio @@ -692,7 +842,7 @@ directory. In the latter case, the directory is traversed recursively and all files which are recognized as valid audio files are added to the database. -### The attribute table ### +

    The attribute table

    The attribute table contains two columns, _name_ and _bitnum_. An attribute is simply a name for a certain bit number in the attribute @@ -752,7 +902,7 @@ Read the output of for more information and a complete list of command line options to these commands. -### Blob tables ### +

    Blob tables

    The image, lyrics, moods and playlists tables are all blob tables. Blob tables consist of three columns each: The identifier which is @@ -779,7 +929,7 @@ Note that the images and lyrics are not interpreted at all, and also the playlist and the mood blobs are only investigated when the mood or playlist is activated with the select command. -### The score table ### +

    The score table

    The score table describes those audio files which are admissible for the current mood or playlist (see below). The table has two columns: @@ -805,7 +955,7 @@ terms of attributes and other type of information available in the audio file table. As an example, a mood can define a filename pattern, which is then matched against the names of audio files in the table. -### Playlists ### +

    Playlists

    Playlists are accommodated in the playlist table of the afs database, using the aforementioned blob format for tables. A new playlist is @@ -824,7 +974,7 @@ in descending order so that files will be selected in order. If a file could not be opened for streaming, its entry is removed from the score table (but not from the playlist). -### Moods ### +

    Moods

    A mood consists of a unique name and its *mood definition*, which is a set of *mood lines* containing expressions in terms of attributes @@ -899,7 +1049,7 @@ special treatment: -### List of mood_methods ### +

    List of mood_methods

    no_attributes_set @@ -945,7 +1095,7 @@ if the year tag is a two-digit number. In this case either 1900 or greater than 2000 plus the current year. -### Mood usage ### +

    Mood usage

    To create a new mood called "my_mood", write its definition into some temporary file, say "tmpfile", and add it to the mood table @@ -973,7 +1123,7 @@ if the "-a" switch is given: para ls -a -### Example mood definition ### +

    Example mood definition

    Suppose you have defined attributes "punk" and "rock" and want to define a mood containing only Punk-Rock songs. That is, an audio file should be @@ -1062,7 +1212,7 @@ Audio formats The following audio formats are supported by paraslash: -### MP3 ### +

    MP3

    Mp3, MPEG-1 Audio Layer 3, is a common audio format for audio storage, designed as part of its MPEG-1 standard. An MP3 file is made up of @@ -1072,7 +1222,7 @@ of channels. For a typical CD-audio file (sample rate of 44.1 kHz stereo), encoded with a bit rate of 128 kbit, an MP3 frame is about 400 bytes large. -### OGG/Vorbis ### +

    OGG/Vorbis

    OGG is a standardized audio container format, while Vorbis is an open source codec for lossy audio compression. Since Vorbis is most @@ -1082,7 +1232,7 @@ chunks called OGG pages. A typical OGG page is about 4KB large. The Vorbis codec creates variable-bitrate (VBR) data, where the bitrate may vary considerably. -### OGG/Speex ### +

    OGG/Speex

    Speex is an open-source speech codec that is based on CELP (Code Excited Linear Prediction) coding. It is designed for voice @@ -1092,7 +1242,7 @@ supported. As for Vorbis audio, Speex bit-streams are often stored in OGG files. As of 2012 this codec is considered obsolete since the Oppus codec, described below, surpasses its performance in all areas. -### OGG/Opus ### +

    OGG/Opus

    Opus is a lossy audio compression format standardized through RFC 6716 in 2012. It combines the speech-oriented SILK codec and the @@ -1101,7 +1251,7 @@ OGG/Vorbis and OGG/Speex, Opus data is usually encapsulated in OGG containers. All known software patents which cover Opus are licensed under royalty-free terms. -### AAC ### +

    AAC

    Advanced Audio Coding (AAC) is a standardized, lossy compression and encoding scheme for digital audio which is the default audio @@ -1109,7 +1259,7 @@ format for Apple's iPhone, iPod, iTunes. Usually MPEG-4 is used as the container format and audio files encoded with AAC have the .m4a extension. A typical AAC frame is about 700 bytes large. -### WMA ### +

    WMA

    Windows Media Audio (WMA) is an audio data compression technology developed by Microsoft. A WMA file is usually encapsulated in the @@ -1118,7 +1268,7 @@ how meta data about the file is to be encoded. The bit stream of WMA is composed of superframes, each containing one or more frames of 2048 samples. For 16 bit stereo a WMA superframe is about 8K large. -### FLAC ### +

    FLAC

    The Free Lossless Audio Codec (FLAC) compresses audio without quality loss. It gives better compression ratios than a general purpose @@ -1583,7 +1733,7 @@ they are usually placed directly after the decoding filter. Each sample is multiplied with a scaling factor (>= 1) which makes amp and compress quite expensive in terms of computing power. -### amp ### +

    amp

    The amp filter amplifies the audio stream by a fixed scaling factor that must be known in advance. For para_audiod this factor is derived @@ -1610,7 +1760,7 @@ To store V in the audio file table, the command is used. The reader is encouraged to write a script that performs these computations :) -### compress ### +

    compress

    Unlike the amplification filter, the compress filter adjusts the volume of the audio stream dynamically without prior knowledge about the peak @@ -1831,12 +1981,14 @@ welcome. Here's a list of things you can do to help the project: - Compile and test on your favorite architecture or operating system. The code is tested only on a limited set of systems, so you will probably encounter problems when building on different systems. -- Post about about paraslash on your blog or on social networks. +- Post about paraslash on your blog or on social networks. - Build and maintain Debian/RPM packages for your favorite distribution. Note that there is no mailing list, no bug tracker and no discussion forum for paraslash. If you'd like to contribute, or have questions about contributing, send email to Andre Noll . +New releases are announced by email. If you would like to receive +these announcements, contact the author through the above address. Tools ----- @@ -2025,14 +2177,14 @@ Appendix Network protocols ----------------- -### IP ### +

    IP

    The _Internet Protocol_ is the primary networking protocol used for the Internet. All protocols described below use IP as the underlying layer. Both the prevalent IPv4 and the next-generation IPv6 variant are being deployed actively worldwide. -### Connection-oriented and connectionless protocols ### +

    Connection-oriented and connectionless protocols

    Connectionless protocols differ from connection-oriented ones in that state associated with the sending/receiving endpoints is treated @@ -2048,7 +2200,7 @@ up-to-date internal state of the connection also in general means that the sending endpoints perform congestion control, adapting to qualitative changes of the connection medium. -### Reliability ### +

    Reliability

    In IP networking, packets can be lost, duplicated, or delivered out of order, and different network protocols handle these @@ -2060,7 +2212,7 @@ out-of-order. Retransmission is used to guarantee loss-free delivery. Unreliable protocols, in contrast, do not guarantee ordering or data integrity. -### Classification ### +

    Classification

    With these definitions the protocols which are used by paraslash for steaming audio data may be classified as follows. @@ -2071,7 +2223,7 @@ steaming audio data may be classified as follows. Below we give a short descriptions of these protocols. -### TCP ### +

    TCP

    The _Transmission Control Protocol_ provides reliable, ordered delivery of a stream and a classic window-based congestion control. In contrast @@ -2082,7 +2234,7 @@ extensively by many application layers. Besides HTTP (the Hypertext Transfer Protocol), also FTP (the File Transfer protocol), SMTP (Simple Mail Transfer Protocol), SSH (Secure Shell) all sit on top of TCP. -### UDP ### +

    UDP

    The _User Datagram Protocol_ is the simplest transport-layer protocol, built as a thin layer directly on top of IP. For this reason, it offers @@ -2093,7 +2245,7 @@ means that there is no protection against packet loss or network congestion. Error checking and correction (if at all) are performed in the application. -### DCCP ### +

    DCCP

    The _Datagram Congestion Control Protocol_ combines the connection-oriented state maintenance known from TCP with the @@ -2110,7 +2262,7 @@ the choice of congestion control: classic, window-based congestion control known from TCP is available as CCID-2, rate-based, "smooth" congestion control is offered as CCID-3. -### HTTP ### +

    HTTP

    The _Hypertext Transfer Protocol_ is an application layer protocol on top of TCP. It is spoken by web servers and is most often used @@ -2120,7 +2272,7 @@ delivery of web pages only. Being a simple request/response based protocol, the semantics of the protocol also allow the delivery of multimedia content, such as audio over http. -### Multicast ### +

    Multicast

    IP multicast is not really a protocol but a technique for one-to-many communication over an IP network. The challenge is to deliver