From 770cd61fe93347933c957e8da6de499a5dcb64fd Mon Sep 17 00:00:00 2001 From: Jakob Pfender Date: Fri, 15 Oct 2010 10:39:58 +0200 Subject: documentation for media.erl --- server/media.erl | 69 ++++++++++++++++++++++++++------------------------------ 1 file changed, 32 insertions(+), 37 deletions(-) diff --git a/server/media.erl b/server/media.erl index 8c60f10..4710cac 100644 --- a/server/media.erl +++ b/server/media.erl @@ -3,23 +3,23 @@ -define(TESTPATTERN, "../ac/*.mp3"). -define(TIMEOUT, 100000000). -%This module is responsible for the management of the music database. -%It keeps track of playlist items with their current voting and locked/unlocked status -%and automatically selects the next song with the highest vote count to play back. +%% This module is responsible for the management of the music database. +%% It keeps track of playlist items with their current voting and locked/unlocked status +%% and automatically selects the next song with the highest vote count to play back. -% Since we are not willing to calculate and deliver all the id3 tags everytime they are requested, -% we try to get something persistent with mnesia. -% Concerning the parsing of id3tags we use the library id3v2 by Brendon Hogger. For detailed information take a -% look at the header of the library. +%% Since we are not willing to calculate and deliver all the id3 tags everytime they are requested, +%% we try to get something persistent with mnesia. +%% Concerning the parsing of id3tags we use the library id3v2 by Brendon Hogger. For detailed information take a +%% look at the header of the library. -% What is an entry in our database made of? By the way the filepath includes the filename. +%% What is an entry in our database made of? By the way the filepath includes the filename. -record(track, {title, artist, votes, locked, filepath }). -% Before this module becomes usable, we must initialize it with the following steps: -% 1. Initialize the mnesia database and create the table within it. -% 2. Parse the mp3s in the working directory and add them to the database -% 3. Get into a loop so the database can be queried and files can be played. +%% Before this module becomes usable, we must initialize it with the following steps: +%% 1. Initialize the mnesia database and create the table within it. +%% 2. Parse the mp3s in the working directory and add them to the database +%% 3. Get into a loop so the database can be queried and files can be played. init() -> mnesia:create_schema([node()]), @@ -30,8 +30,8 @@ init() -> io:format("Starting to play music~n"), start_playing(). -% uses the algorithm of Brendon Hogger to split the id3-tags and -% inserts the songs into the Database +%% uses the Brendon Hogger's algorithm to split the id3 tags and +%% inserts the songs into the Database read_files([FN|Rest],Total,Fail) -> case id3v2:read_file(FN) of @@ -44,14 +44,14 @@ read_files([FN|Rest],Total,Fail) -> end; read_files([],Total,Fail) -> io:format("Total: ~w, Failed: ~w~n", [Total, Fail]). -% Our loop to play music all the time, play waits on exit_status +%% Our loop to continuously play music, play waits on exit_status start_playing() -> {Artist, Title} = search_best(media:all(), 0,0), play(Artist, Title). -% Basic insertion of entries into the database. Some entries are left out because they are 0 or false. +%% Basic insertion of entries into the database, including vote count and lock status. Some entries are left out because they are 0 or false. insert(Artist, Title, Filepath) -> F = fun() -> @@ -59,10 +59,10 @@ insert(Artist, Title, Filepath) -> end, mnesia:transaction(F). -% Of course we need a query to find out whats actually the most wished for track. -% We will do it by requesting all the records from the database and then iteramte over just taking a look at the vote -% variable, so it is like list of integers. In case no tracks were voted for we just take the first track we find and play it. -% Of course it is locked afterwards so another will be choosen. +%% Of course we need a query to find out what the most requested track is. +%% We accomplish this by requesting all the records from the database and then iterating over them just taking a look at the vote +%% count, so it is like list of integers. In case several tracks share the highest vote count we just take the first track with the highest vote count +%% we found and play it. Of course the song is locked afterwards, so in case no one ever votes the playlist just cycles like a normal playlist. search_best([Head|Rest], Max_Votes, Track) -> @@ -74,14 +74,14 @@ search_best([Head|Rest], Max_Votes, Track) -> search_best([], 0, 0) -> reset_all(all()); search_best([], _, Track) -> {Track#track.artist, Track#track.title}. -% if nothing is playable anymore (because all songs are locked) just reset all songs and start playing again... +%% if nothing is playable anymore (because all songs are locked) just reset all songs and start from the beginning ... reset_all([Head|Rest]) -> unlock(Head#track.artist, Head#track.title), reset_all(Rest); reset_all([]) -> ok. -% We want to query in order to simplify the next calls. +%% We want to query in order to simplify the next calls. ask(Artist, Title) -> F = fun() -> @@ -90,7 +90,7 @@ ask(Artist, Title) -> {atomic, Results} = mnesia:transaction(F), Results. -% Just in case the client is interested in everything we have. +%% Just in case the client is interested in everything we have. all() -> F = fun() -> @@ -99,9 +99,8 @@ all() -> {atomic, Results} = mnesia:transaction(F), Results. -% We want to play mp3s from our database. After we play them they will be locked. -% In practice we are going to set their locked variable to true and spawn a process which will unlock them after a certain time. -% Well this could be considered abuse. +%% We want to play mp3s from our database. After we have played them they will be locked. +%% In practice we are going to set their locked variable to TRUE and spawn a process which will unlock them after a certain time. play(Artist, Title) -> [Head|_] = ask(Artist, Title), @@ -117,11 +116,7 @@ play(Artist, Title) -> end. -% Of course we need a query to find out what the highest voted track is. -% We accomplish this by requesting all the records from the database and then iterate over them, just taking a look at the vote -% variable, so it is like a list of integers. In case no tracks were voted for we just take the first track we found and play it. Of course this song is locked afterwards so a different one will be chosen. - -%votes for a track, i.e. increases its vote count by one. +%% votes for a track, i.e. increases its vote count by one. vote(Artist, Title) -> F = fun() -> [Head|_] = ask(Artist, Title), @@ -131,7 +126,7 @@ vote(Artist, Title) -> end, mnesia:transaction(F). -%votes against a track, i.e. decreases its vote count by one. +%% votes against a track, i.e. decreases its vote count by one. devote(Artist, Title) -> F = fun() -> [Head|_] = ask(Artist, Title), @@ -141,7 +136,7 @@ devote(Artist, Title) -> end, mnesia:transaction(F). -%resets the vote count of selected track to 0 (this is called when the song is played). +%% resets the vote count of selected track to 0 (this is called when the song is played). reset_votes(Artist, Title) -> F = fun() -> [Head|_] = ask(Artist, Title), @@ -150,7 +145,7 @@ reset_votes(Artist, Title) -> end, mnesia:transaction(F). -%locks a song so it can't be played again or voted for for that time. +%% locks a song so it can't be played again for a certain time. lock(Artist, Title) -> F = fun() -> [Head|_] = ask(Artist, Title), @@ -159,7 +154,7 @@ lock(Artist, Title) -> end, mnesia:transaction(F). -%unlocks a song so it can be played and voted for again. +%% unlocks a song so it can be played again. unlock(Artist, Title) -> F = fun() -> [Head|_] = ask(Artist, Title), @@ -168,8 +163,8 @@ unlock(Artist, Title) -> end, mnesia:transaction(F). -% Lock a song if it was just played, after a Timeout it will be unlocked automaticly -% If all songs are locked, all will be unlocked. +%% Lock a song if it was just played, after a timeout it will be unlocked automatically +%% If all songs are locked, they will all be unlocked. lock_process(Artist, Title) -> lock(Artist, Title), receive -- cgit v1.2.3