{"id":18318579,"url":"https://github.com/grahammitchell/voteamp","last_synced_at":"2025-06-11T14:10:42.213Z","repository":{"id":156778902,"uuid":"95393568","full_name":"grahammitchell/voteamp","owner":"grahammitchell","description":"voteamp is a collection of linux programs for the purpose of selecting and playing a list of audio tracks by popular vote.","archived":false,"fork":false,"pushed_at":"2017-06-26T00:33:41.000Z","size":478,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-02-15T07:51:21.413Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/grahammitchell.png","metadata":{"files":{"readme":"README","changelog":"HISTORY","contributing":null,"funding":null,"license":"COPYING","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-06-26T00:26:43.000Z","updated_at":"2017-06-26T00:28:15.000Z","dependencies_parsed_at":null,"dependency_job_id":"ed4f0041-7a75-48da-808d-4fd9ed791e1d","html_url":"https://github.com/grahammitchell/voteamp","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grahammitchell%2Fvoteamp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grahammitchell%2Fvoteamp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grahammitchell%2Fvoteamp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grahammitchell%2Fvoteamp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/grahammitchell","download_url":"https://codeload.github.com/grahammitchell/voteamp/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248054217,"owners_count":21039951,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-05T18:10:24.751Z","updated_at":"2025-04-09T13:54:44.852Z","avatar_url":"https://github.com/grahammitchell.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"voteamp 0.1.0 (c) 1999 Graham Mitchell - 25 Jul 99\n\n0) TABLE OF CONTENTS\n\n    1) A NOTE\n    2) INTRODUCTION\n    3) INCLUDED PROGRAMS\n    4) THE NETWORK PROTOCOL\n    5) INSTALLATION\n    6) KNOWN BUGS\n    7) REGISTRATION\n    8) ADDITIONAL INFORMATION\n\n\n1) A NOTE\n\n    The code in the archive is ALPHA code.  That is, it compiles on my linux\n    system and works with limited functionality, but is by no means\n    feature-complete. However, it serves as a proof of concept and a\n    framework for future development.  Do not use this if you are not\n    comfortable with experimental software.\n    \n    This documentation is fairly poor and assumes you know certain things\n    about using a linux system and compiling and using alpha software.\n    Certainly this documentation will improve as the software behind it does.\n    \n\n2) INTRODUCTION\n\n    The short version:\n    \n    voteamp is a collection of programs for the purpose of selecting and\n    playing a list of audio tracks by popular vote.  It requires that xaudio\n    be installed on your computer.  There is also a necessary client program\n    (for voting) which is currently not included.\n\n    The long version:\n    \n    voteamp is not so much a single program as it is a SYSTEM.  It is a\n    collection of five programs (three included), perl scripts, cron jobs and\n    various text files designed to accomplish a single purpose.  It very\n    much follows the UNIX tools philosophy making it less usable for the\n    novice user but much more flexible for the expert.  All code included\n    here is covered under the GNU General Public License (see the file\n    COPYING) for details.\n\n    Here's what it does.  Note that I am a high school computer science\n    teacher by day, so this is an account of how my students have used it for\n    a semester.\n\n    In the corner of the room sits a linux server box with a hard drive full\n    of (legal) mp3s.\n\n    Students come into the classroom and sit down at their machines.  They\n    log in and launch a Win32 client program (not included) which shows them\n    all available albums.  They select albums they want to hear and vote\n    against albums they don't.  They submit their vote, which goes to the\n    linux box in the corner via TCP/IP.\n\n    The server checks to make sure the student voting is allowed to do so\n    (the client sends the student's network login with the vote); if so,\n    their vote is tallied.\n\n    After several students have voted, the server produces a list of winning\n    albums, generates a random playlist of tracks off those albums, and the\n    music begins.  Any subsequent votes cause a retally, a new list of\n    winning albums, and a new playlist, which goes into effect once the\n    current song is over.  At the end of the period, the music stops, the\n    server resets with a new list of eligible students (those about to come\n    in the following period) and the whole process begins again.\n\n\n3) INCLUDED PROGRAMS\n\n    Basically, the meat of this system consists of five programs and a cron\n    job.\n\n    (1) rxaudio - a free mp3 player which takes commands on stdin (not the\n    command line) available from \u003chttp://www.xaudio.com/\u003e  I did not write\n    this program and have nothing to do with its development.\n\n    (2) fxaudio - a daemon which launches rxaudio, redirecting stdin and\n    stdout to a pipe.  It reads a playlist and instructs rxaudio to play each\n    track in turn.  It runs continually unless instructed not to (with the\n    -quit command-line option), automatically reloads the playlist when it\n    changes (though it doesn't stop the currently playing song), waits\n    patiently for a new playlist when its playlist is empty or it has\n    finished playing all the songs on the list, and immediately advances to\n    the next track on the playlist when it receives signal USR1.\n\n    Currently this program requires rxaudio to run.  However, eventually I'd\n    like to replace this with a modified version of freeamp with the same\n    functionality.\n\n    (3) voted - a daemon which receives TCP/IP votes from a client program,\n    checks them against a list of valid users, tallies them up, and writes\n    out a list of winning \"items\" in order of votes when a predefined number\n    of valid votes have been received.  Once a particular user has voted,\n    subsequent votes attributed to that user are cheerfully ignored until the\n    server is reset (use signal HUP).\n\n    This code was originally a basic web server when I first wrote it back in\n    college.  I think some of the lines came from one of my TAs, who got it\n    from Comer's TCP/IP book.\n\n    Unfortunately, this code does not fork.  Though my original \"web server\"\n    did, this cannot because each process receives votes and must add them to\n    the global total.  Plans are to rewrite this so it will fork and allow\n    the forked processes to send vote data through IPC but be aware it\n    currently does not do this.  The multiplexing strategy at the moment is\n    just \"block waiting connections and finish the current connection\n    quickly\".\n\n    There is no security in this code, which it desperately needs.  At the\n    moment, security is handled through obscurity because most of my students\n    (first-year computer science) wouldn't know how to work around it even if\n    they examined the code.  Of course, this is one of the highest priorities\n    if this code is going to be useful on a large scale.\n\n    (4) listmaker - another daemon which converts the list of winning albums\n    produced by voted into a random playlist of tracks off the winning\n    albums. It monitors its input file for changes.  When they occur, it\n    writes an output file with the new results.\n\n    The song selection scheme works like this: the first line in the file is\n    assumed to be a text file containing a list of songs.  This file is\n    opened for reading.  For each line in the songlist, there is a 66% chance\n    that the current line will be chosen for inclusion in the final playlist.\n    This continues for each song in the file, meaning that on average, 2/3 of\n    the winning album will make it to the result playlist.  Then the\n    second-most-popular album file is opened, and each song has a 33% chance\n    of being chosen.  The songs from the third album have a 16.5% chance, and\n    so on. For later albums, the per-song percentage never drops below 1%,\n    usually meaning that there's about a 10% that one song from the album\n    will make it on the final playlist.  Once all the albums on the winning\n    list have been examined, the final playlist is randomized and written out\n    to the output file.\n\n    (5) VoteBot - a Win32 GUI client that presents the list of songs and\n    allows voting.  This is not included, not because I want to hide\n    information about it but because it's written in Borland C++ Builder 3\n    and I don't know how to package up that code so that it will compile\n    somewhere else.  It reads the same ballot file that voted uses to display\n    the list of songs.  It gets the username for each vote from the registry\n    and so sends each student's NetWare login name as their username.\n\n    Soon I hope to have a console application for linux that will accomplish\n    the same purpose, and a GUI app. for linux would be great, though I don't\n    know how to write one.\n\n    (6) the cron job - as I mentioned, students are in my classroom only for\n    a period at a time.  It is not desirable to allow people to vote who are\n    not physically near the speakers (i.e. in another classroom).  Of course,\n    I also want to reset the voting at the beginning of each period.  I use a\n    cron job for the purpose timed with the bell schedule: it overwrites the\n    list of allowed users with the list of student logins for students\n    arriving.  It also calls a perl script (included) which sends a HUP\n    signal to the vote server, restarting it and causing it to reread all its\n    configuration files. The cron job statements I use (not particularly\n    interesting) are included as \"crontab.sample\".\n\n\n4) THE NETWORK PROTOCOL\n\n    At the moment, the network protocol is mind-numbingly simple and\n    amazingly insecure.  The client sends a packet containing a username and\n    vote.  The server returns a packet containing the ASCII string \"ACK\" if\n    the vote counted (i.e. it was from an allowed user who had not already\n    voted) and \"NACK\" otherwise.\n\n    Say the list of albums in the ballot is like this:\n\n        1) Black Crowes - Shake Your Moneymaker\n        2) Eagles - Greatest Hits Vol. 2\n        3) Jimi Hendrix - Are You Experienced?\n        4) Lynyrd Skynyrd - Skynyrd's Innyrds\n        5) Pearl Jam - Ten\n        6) Rage Against The Machine - Evil Empire\n        7) Stevie Ray Vaughn - The Sky is Crying\n\n    Say I wish to vote for Pearl Jam and Stevie Ray Vaughn, vote against\n    Lynyrd Skynyrd, and I have no preference for the other four albums.  Also\n    presume my login name is \"MitchGr\".  My \"vote\" will look like so:\n\n    MitchGr AAAzZAZ\n\n    The alphabetic string after the login name (which will be compared,\n    case-insensitively, to the list of allowed users) is a list of yea/nay\n    votes for each song in the ballot, in the order in which they occur.\n    Each vote has variable strength ranging from lowercase z (25 points\n    against) to uppercase Z (25 points for) with both capital and lowercase A\n    being worth zero points.\n\n    This level of discrimination is intended to distinguish between voters\n    who vote for EVERYTHING versus someone who has merely one album which\n    they strongly want to hear.  The client currently enforces this by\n    assigning 75 \"points\" for each voter.  Each album up to three uses 25\n    points (since that's the maximum vote anyway).  After three selections,\n    points are evenly distributed among all votes.  So a person who wanted to\n    hear everything on the list would have a vote that looked like this:\n\n    MitchGr KKKKKKK\n\n    Thus the 75 points were distributed among seven votes of eleven apiece\n    (the client rounds up).  Currently the server does not sanity check\n    votes, so a vote of:\n\n    MitchGr zzzzzzz\n\n    would be accepted (-25 points for each of seven albums).\n\n    Albums with a positive score once the voting settles make it to the final\n    playlist.\n\n\n5) INSTALLATION\n\n    Okay, this doesn't really tell you how to \"install\" the program, but it\n    does tell you how to get everything running. With this release, you're\n    pretty much on your own.  You might want to look at the shell script\n    \"vote.pl\" to see how I launch things.  Of course, you'll need to compile\n    the three included programs within their respective directories.  I've\n    written a Makefile for each, at least, though not a global Makefile to do\n    the whole thing.  And don't even bother trying \"make install\".\n\n    On my machine, I have a whole hard drive devoted to holding mp3s mounted\n    on /music.  Files are stored by artist and then by album, so for example\n    Purple Haze is stored in:\n\n    /music/Jimi_Hendrix/Are_You_Experienced/Purple_Haze.mp3\n\n    The \"Are_You_Experienced\" directory also contains a playlist for all\n    songs in that directory called \"album.m3u\".  On my machine, the tracks\n    are listed in album order, though of course this is not necessary. The\n    name \"album.m3u\" is currently hard-coded into songlist.pl and another\n    program (listmaker) expects filenames in the playlist to be local.  That\n    is:\n\n        Purple_Haze.mp3\n        Manic_Depression.mp3\n        Hey_Joe.mp3\n\n    and NOT\n\n        /music/Jimi_Hendrix/Are_You_Experienced/Purple_Haze.mp3\n        /music/Jimi_Hendrix/Are_You_Experienced/Manic_Depression.mp3\n        /music/Jimi_Hendrix/Are_You_Experienced/Hey_Joe.mp3\n\n    I run the perl script songlist.pl from the root of the mp3 drive\n    (/music), and redirect the output to a file called \"songs.bal\".  This\n    file contains the human-readable name of the artists/albums followed by\n    the path to the songlist for that album.  That is, it looks like:\n\n    Jimi Hendrix - Are You Experienced\n    /music/Jimi_Hendrix/Are_You_Experienced/album.m3u\n    Rage Against The Machine - Evil Empire\n    /music/Rage_Against_The_Machine/Evil_Empire/album.m3u\n    (etc...)\n\n    This file is the \"ballot\", used by both the voting server and the client.\n    The client reads the first of each pair of lines (the human-readable\n    name) and the server reads the latter of each pair (the path), but the\n    only thing that is vitally important is that both lists end up in the\n    same order (i.e. make sure you're not sorting the list of names in the\n    client and not in the server or vice-versa).\n\n    Currently both the server and client sort the ballot file alphabetically.\n    The server does so case-insensitively.  Sorting these is probably a Bad\n    Idea; the perl script should handle any necessary sorting but it does\n    not.  Just be aware of this.\n\n    So I manually copy the ballot file into the voting server directory and\n    into the client program directory.  Once I get the server forking\n    properly, I plan to just send the ballot file across the network\n    (essentially via HTTP) if the client doesn't have it or has an old copy.\n\n    I then set up my cron jobs to reset the server timed with the\n    bell-schedule and to replace the list of valid users every period.  It's\n    important to overwrite the allowed users *before* resetting the server,\n    since the server rereads its configuration files only when reset.\n\n    Once that's done, I erase whatever the last \"winning\" playlist was (or\n    rather, I overwrite it with a zero-length file.  I imagine fxaudio would\n    panic if it was started referencing a non-existent file).\n\n    I then run fxaudio in the background, telling it to play songs from the\n    empty playlist. It finds it empty and goes into daemon mode, waking up\n    every ten seconds to see if it has something to do.  Once it finds its\n    playlist non-empty, it begins playing the first song.  Once the list is\n    over, it returns to daemon mode.\n\n    Then I run voted in the background.  It will wait for votes and produce a\n    list of winning albums in a predefined location once enough votes have\n    been received.  The list of albums is sorted such that the most popular\n    album is first in the list.  Ties are simply copied down in alphabetical\n    order (probably a bit unfair since ties are somewhat frequent).  Once the\n    voting threshold has been reached, any subsequent votes cause the list of\n    winning albums to be regenerated.\n\n    Finally I run listmaker in the background, telling it to make lists of\n    songs from the list of albums.  I give it voted's winning album list as\n    an input file and the currently-empty playlist as an output file.\n    Similar to fxaudio, it mostly sleeps, only waking up every ten seconds to\n    see if anything has changed.  Once it has a list of albums to work with,\n    it produces the outfile of songs with full pathnames by appending the\n    track file name (i.e. Fire.mp3) to the path from the ballot (which is\n    what voted writes out for \"winners\").\n\n    That is, given a winning album:\n\n    /music/Jimi_Hendrix/Are_You_Experienced/album.m3u\n\n    It opens album.m3u in that directory, chooses songs:\n        Manic_Depression.mp3\n        Hey_Joe.mp3\n\n    and writes:\n\n    /music/Jimi_Hendrix/Are_You_Experienced/Manic_Depression.mp3\n    /music/Jimi_Hendrix/Are_You_Experienced/Hey_Joe.mp3\n\n    to the output file.  (Well, technically it randomizes the list first, but\n    that's the idea.)\n\n    Eventually fxaudio notices its input file has changed, rereads it, and\n    begins playing the first song.\n\n    Note that since voted rewrites the results every time additional votes\n    are received, listmaker produces a new playlist every time its input file\n    changes, and fxaudio plays new lists when it gets them, the song list is\n    fairly dynamic.\n    \n\n    At the end of the period the cron job kicks in, rewriting the list of\n    allowed voters and resetting the server to zero out any existing votes.\n    The process begins again.  There is much good music played.  Everyone is\n    happy.\n\n6) KNOWN BUGS\n\n    Don't even get me started.  This is alpha code, remember?  There are no\n    show-stoppers that I know of.  You can find lists of things I'd like to\n    change by reading this document, by reading the files called TODO in the\n    directory for each program, and by searching for FIXME in the source\n    files.\n\n    However, one peculiarity should be mentioned.  If voting is fairly\n    sporadic throughout a voting period, you might hear the same song\n    multiple times. Consider the following scenario (which happens in my\n    classroom fairly often).\n\n    1) Lots of students vote.\n    \n    2) voted chooses a list of winning albums (say Pearl Jam's \"Ten\" is number\n        one).\n    \n    3) listmaker produces a list with a lot of Pearl Jam songs, including\n        \"Jeremy\", which is about four songs down.\n    \n    4) The class hears a good half-hour worth of music, including \"Jeremy\".\n    \n    5) Johnny submits a vote, voting for \"The Mulan Soundtrack\" and nothing\n        else.\n    \n    6) Since he didn't vote against Pearl Jam, it remains the number one\n        album. However, since new votes were received, voted writes a new\n        list of winning albums, now including Mulan (which is at the bottom\n        of the list since it presumably received only one vote).\n    \n    7) listmaker notices a changed file and produces a new list.  Since Ten\n        is still the number one album, the list has a lot of Pearl Jam songs,\n        including \"Jeremy\", which is about two songs down (remember they are\n        random).\n    \n    8) The class hears \"Jeremy\" twice in the span of forty-five minutes.\n\n    This problem can be even more aggravating when Johnny votes AGAINST Pearl\n    Jam, but it is popular enough to still be number one even after his\n    negative vote. Thus assuming the list had been playing for a while,\n    Johnny gets to hear even more Pearl Jam for his trouble.  I plan to fix\n    this in the future.\n\n7) REGISTRATION\n\n    This program is free software; you can redistribute it and/or\n    modify it under the terms of the GNU General Public License\n    as published by the Free Software Foundation; either version 2\n    of the License, or (at your option) any later version.\n\n    This program is distributed in the hope that it will be useful,\n    but WITHOUT ANY WARRANTY; without even the implied warranty of\n    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the\n    GNU General Public License (COPYING) for more details.\n\n    You should have received a copy of the GNU General Public License\n    along with this program; if not, write to the Free Software Foundation,\n    Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.\n\n    If you enjoy this program, I'd appreciate it if you drop me a line\n    saying so.  Please send any bug reports to me, as well.  If you'd like\n    to aid in the development of this program, that would also be very\n    spiffy.\n    \n    I wrote this program to scratch an itch, and have made it available\n    thinking that perhaps there are others who would find it useful.  I do\n    not need or expect any money from you if you use it; this is freeware in\n    every sense of the word.  However, if you really feel you should send me\n    money, I guess that'd be okay, too.\n\n\n8) ADDITIONAL INFORMATION\n\n    Name:       voteamp-0.1.0.tar.gz\n    Version:    0.1.0  (alpha)\n    Author:     Graham Mitchell\n    Mail:       \u003credacted\u003e\n    Email:      \u003credacted\u003e\n    WWW:        https://grahammitchell.com/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgrahammitchell%2Fvoteamp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgrahammitchell%2Fvoteamp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgrahammitchell%2Fvoteamp/lists"}