{"id":16651169,"url":"https://github.com/cbefus/camel-a-framework-for-audio-analysis","last_synced_at":"2025-04-09T17:31:30.751Z","repository":{"id":1293723,"uuid":"1235121","full_name":"cbefus/CAMEL-A-Framework-for-Audio-Analysis","owner":"cbefus","description":"CAMEL (Content-based Audio and Music Extraction Library) is an easy-to-use C++ framework developed for content-based audio and music analysis. The framework provides a set of tools for easy Segmentation, Feature Extraction, Domain Extraction, etc. ","archived":false,"fork":false,"pushed_at":"2013-06-21T21:10:34.000Z","size":632,"stargazers_count":21,"open_issues_count":0,"forks_count":6,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-03-23T19:39:06.766Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://sourceforge.net/projects/camel-framework/","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cbefus.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2011-01-09T13:40:29.000Z","updated_at":"2024-03-06T15:09:19.000Z","dependencies_parsed_at":"2022-08-16T13:00:19.028Z","dependency_job_id":null,"html_url":"https://github.com/cbefus/CAMEL-A-Framework-for-Audio-Analysis","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/cbefus%2FCAMEL-A-Framework-for-Audio-Analysis","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cbefus%2FCAMEL-A-Framework-for-Audio-Analysis/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cbefus%2FCAMEL-A-Framework-for-Audio-Analysis/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cbefus%2FCAMEL-A-Framework-for-Audio-Analysis/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cbefus","download_url":"https://codeload.github.com/cbefus/CAMEL-A-Framework-for-Audio-Analysis/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248077325,"owners_count":21043939,"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-10-12T09:24:00.453Z","updated_at":"2025-04-09T17:31:30.399Z","avatar_url":"https://github.com/cbefus.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n\nWelcome to Content-based Audio and Music Extraction Library.  The main purpose of this library is to give simple access to the common MIR extraction functions without a massive learning curve or the restrictions of GUIs. For more information on the reasoning and design considerations behind CAMEL see C. Sanden, C. Befus, and J. Zhang, CAMEL: A lightweight Framework for Content-based Audio and Music Analysis, In Proceedings of Audio Mostly, Piteå, Sweden, 2010. \n\nThis readme will outline the following\n\n0. License\n\n1. Using CAMEL\n1.1 Building the library and Dependencies\n1.2 Creating the proper input file format (PCM ASCII text)\n1.3 Extracting a Domain from a file using CAMEL\n1.4 List of Domains in CAMEL (with identifiers for switch/settings)\n1.5 Extracting a Feature from a file using CAMEL\n1.6 List of Features in CAMEL (with identifiers for switch/settings)\n1.7 Extracting Segmentations from a file using CAMEL\n1.8 List of Segmentations in CAMEL (with identifiers for switch/settings)\n\n2. Extending CAMEL\n2.1 Adding a Domain to CAMEL\n2.2 Adding a Feature to CAMEL\n2.3 Adding a Segmentation to CAMEL\n\n\n0. License\n-----------\n\nCopyright (c) 2010 Chad R. Befus, Chris Sanden, Cody Rioux\n\t\nCAMEL (Content-based Audio and Music Extraction Library) is unrestricted, open \nsource \"software\", with respect, but not limited, to modification, use, \npublishing, and distribution, subject to the following conditions:\n\n1. This copyright notice is maintained in its current form throughout CAMEL.\n\n2. Any publication or distribution credits the usage of CAMEL appropriately.\n\t\nThis software is provided \"as is\" without warranty. The authors are in no way\nliable for any misuse or damages arising from the use, modification or \ndistribution of it or any part thereof.\n\n-----------\n\n1. Using CAMEL\n###########\n-----------\n\nEvery file in CAMEL begins with a header which includes License information, \nfile dependencies, and an example usage of the file.  Every function in CAMEL \nbegins with commenting which outlines the parameters, conditions, and methods \nused throughout the function.  Reading these comments can help with the use of \nCAMEL.  Many of the comments for features and domains has the math behind the \nmethodology writting in latex form.  All the code in CAMEL has been evaluated \nagainst the output of several other mainstream extraction libraries and is, \nto that end, correct (though several errors were discoved in other libraries \nduring this testing).\n\nNote: this readme is written assuming the user is using a linux machine.  \nHowever CAMEL has been tested and used successfully on both a windows and \nMac machine.  The content of this readme is still applicable (in most cases) \nto any operating system.\n\n-----------\n\n1.1 Building the library and Dependencies\n-----------\nFirst off, at this point (version 1.0) the only dependency for building CAMEL\nis that the FFTW library be installed on your machine. FFTW is freely available\nand can be found at http://www.fftw.org/.  For the purposes of creating CAMEL \nlibfftw3-dev was used and is recommended for future use.  On a linux terminal \nthis can be installed using: \n\n\t~$ sudo apt-get install libfftw3-dev\n\nBuilding CAMEL in its current form is extremely simple. Assuming your main file is\nnamed main.cpp and you are preforming a segmentation/extraction task the makefile \nprovided should handle the full build process. simply typing:\n\n\t~$ make\n\nshould handle the process.\n\nIf you wish to skip the segmentation task for feature extraction then the lines in the makefile: \n\n\tsegmenter.o : src/segmenter.h src/featureExtract.h\n\tmain.o : src/segmenter.h\n\ncan be replaced with the lines:\n\n\tmain.o : src/featureExtract.h\n\nand the line:\n\n\tfeatExtract : main.o src/segmenter.o src/featureExtract.o src/configFile.o src/domain.o src/feature.o\n\ncan be replaced with:\n\n\tfeatExtract : main.o src/featureExtract.o src/configFile.o src/domain.o src/feature.o\n\nsimilarily if you wish to skip the featureExtract step (only use the domain class) you could \ndo the same steps but removing the featureExtract.o content as well.\n\nIf you wish for your executable to be named something other than featExtract simply rename \nthe word featExtract in the makefile with the one you prefer.\n\nIf you wish to use a file other than main.cpp as your main code file simply replace the word \nmain.o in the makefile with the one you are using.\n\nAfter building CAMEL use: \n\n\t~$ make clean \n\nto remove the temporary files from the build process.  Also:\n\n\t~$ make clean-all\n\nremoves the executable along with the temporary files if you want to do a clean build.\n\n-----------\n\n1.2 Creating the proper input file format\n-----------\nThe input files for CAMEL are in a particular format.  We are working on making a .mp3 decoder\nhowever for the time being we use a PCM  ASCII text print out.  An example file is provided called \nsamplePCM.txt.  The format of these files is a 5 line header explaining the content of the rest \nof the file:\n\nSAMPLES:\t221184\nBITSPERSAMPLE:\t16\nCHANNELS:\t1\nSAMPLERATE:\t44100\nNORMALIZED:\tFALSE\n\nThe samples line gives the number of lines in the file after the header (PCM samples). For CAMEL \nthis line is extremely important as this value is used for much of the processing.  The next \nfour lines are not actually used by CAMEL but are checked and warned about if not matching the \nabove parameters.  CAMEL expects the audio to be in mono at 44100 without normalization.  However \neverything in CAMEL should still work if these things are not true (though some of the maths might\nbe off). If these are not the values you wish to use then it is HIGHLY RECOMMENDED that you adjust \nthe settings in the settings.txt file accordingly.\n\nFollowing the header the PCM format has a single integer value on each new line for the number of\nsamples listed in the header.\n\nWe converted .mp3 files to the format above using Adobe Audition 3.0.  Audition should be able to \nconvert any format of file your data set is in into this format.  (Note we ran Audition on a linux \nsystem using Wine 1.3 -- so no complaining that it is windows only!!).\n\nTo use Adobe Audition to convert to our input format simply open Audition, and under the File menu \nselect to batch processing \n\n\tUnder tab 1: add the data file you intend to convert. \n\tunder tab 3: check off the conversion settings and for destination format select 44100, mono, and 16 bit, \n\tunder tab 4: select ASCII text data (*.txt) as the output format \n\tunder tab 5: set up your destination ect. \n\nFinally hitting Run Batch should make the conversion correctly.  These files are now ready for processing in CAMEL\n\n\n-----------\n\n1.3 Extracting a Domain from a file using CAMEL\n-----------\nIn this section we are assuming you have adjusted the makefile and preprocessed the data as \nexplained above.  Here we give a general explanation and some example code on extracting some \ndomain values from a PCM ASCII text file.\n\nThe simplest example of extracting a domian from CAMEL is to print to screen a single window\nof spectral domain values.  To do this we first open the settings.txt file and adjust the \nappropriate settings for the spectral domain. This includes the settings under headings \n'#PCM Settings' and '#  FFT SPECTRUM'\n\nNext we write a simple main.cpp file.  In it we create an empty domain object, we set the\nfile name for our PCM file in the domain object, we set the window size for our extraction\nto 1024 arbitrarily.  We set the start position of the file to 0. \nWe set the end position to the end of the file (or 10000 arbitrarily).\nWe then call the setup funtion for the domain object allowing it to organize itself.  \nFinally we calculate the spectral domain requested (in the settings file) via the \ngetFrequencyDomainWindow function, passing in the location we wish to start extraction.  \nThen a simple for loop prints the contents of the resulting vector to standard out. Build\nand run.\n\n\n#include \"src/domain.h\"\n#include \u003cvector\u003e\nusing namespace std;\n\nint main(){\t \n\tDomain domain;\n\tdomain.setFileName(\"samplePCM.txt\");\n\tdomain.setWindowSize(1024);\n\tdomain_.setStartPosition(0);\n\tdomain_.setEndPosition(10000);\n\tdomain.setup();\t\n\tvector\u003cdouble\u003e domainVec = domain.getFrequencyDomainWindow(0);\n\tfor(int i = 0; i \u003c 1024; ++i){\n\t\tcout \u003c\u003c domainVec[i] \u003c\u003c endl;\n\t}\n\treturn 0;\n}\n\n-----------\n\n\n1.4 List of Domains in CAMEL (with identifiers for switch/settings)\n-----------\n\nDomains\t\t\tFunction\n1 Time\t\t\tgetTimeDomainWindow()\n2 Spectral\t\tgetFrequencyDomainWindow()\n3 Peak\t\t\tgetPeakDomainWindow()\n\nSpectrums\t\tSwitch Value\t\tFunction\n1 Log Magnitude\t\t1\t\t\tapplyLogMagnitude()\n2 Power\t\t\t2\t\t\tapplyPower()\n3 Log Power\t\t3\t\t\tapplyLogPower()\n4 Magnitude\t\t4\t\t\tapplyMagnitude()\n\t\t\t\n\nWindow Functions\tSwitch Value\t\tFunction\n1 Hann\t\t\t1\t\t\tapplyHann()\n2 Hamming\t\t2\t\t\tapplyHamming()\n3 Triangular\t\t3\t\t\tapplyTriangular()\n4 Bartlett\t\t4\t\t\tapplyBartlett()\n5 Bartlett Hann\t\t5\t\t\tapplyBartlett_hann()\n6 Blackman\t\t6\t\t\tapplyBlackman()\n7 Blackman Harris\t7\t\t\tapplyBlackman_harris()\n8 Rectangular\t\t8\t\t\tapplyRectangular()\n\t\t\t\n\n-----------\n\n1.5 Extracting a Feature from a file using CAMEL\n-----------\nIn this section we are assuming you have adjusted the makefile and preprocessed the data as \nexplained above. Here we give a general explanation and some example code on extracting some \nfeature values from a PCM ASCII text file.\n\nThe simplest example of extracting a feature from CAMEL is to extract the mean from a window\nof the time domain.  To do this we first begin by making appropriate alterations in the settings \nfile. For feature extraction settings manipulate, as needed, values under headings '#PCM Settings',\nand '#Settings for featureExtract class' including '#  FFT SPECTRUM'\n\nNext we write a simple main.cpp.  In our main file we create a feature extraction object.  We \npoint it at our PCM ASCII text file. We set our window size to 1024. We call the setup function \nfor the feature extraction object. We then use the getFeature function to calculate feature 1 (mean)\nfrom between positions 0 and 7000.  we collect the results using the getValues function.  We can\nthen print these results to standard. Note that all results are returned as a vector, clearly for \n1-dimensional results such as the mean we only need to output the first position.\n\n#include \"src/featureExtract.h\"\n#include \u003cvector\u003e\nusing namespace std;\n\nint main(){\t \n\n\tFeatureExtract fe;\n\tfe.setFileName(\"samplePCM.txt\");\n\tfe.setWindowSize(1024);\n\tfe.setup();\n\tfe.getFeature(0, 7000, 1);\n\tvector\u003cdouble\u003e vecFeatureResults = fe.getValues();\n\tcout \u003c\u003c vecFeatureResults[0] \u003c\u003c endl;\n\n}\n\n-----------\n\n\n1.6 List of Features in CAMEL (with identifiers for switch/settings)\n-----------\n\n\nFeature\t\t\tIdentifier\tFunction\n1 Mean\t\t\t\t1\tcalcWindowMean\n2 Variance\t\t\t2\tcalcWindowVariance\n3 Standard Deviation\t\t3\tcalcWindowStandardDeviation\n4 Average Deviation\t\t4\tcalcWindowAverageDeviation\n5 Skewness \t\t\t5\tcalcWindowSkewness \n6 Kurtosis \t\t\t6\tcalcWindowKurtosis \n7 ZCR \t\t\t\t7\tcalcWindowZCR \n8 RMS \t\t\t\t9\tcalcWindowRMS \n9 Non-Zero Count \t\t10\tcalcWindowNonZeroCount \n10 Spectral Centroid \t\t11\tcalcWindowSpectralCentroid \n11 Spectral Variance \t\t12\tcalcWindowSpectralVariance \n12 Spectral Standard Deviation \t13\tcalcWindowSpectralStandardDeviation \n13 Spectral Average Deviation \t14\tcalcWindowSpectralAverageDeviation \n14 Spectral Skewness \t\t15\tcalcWindowSpectralSkewness \n15 Spectral Kurtosis \t\t16\tcalcWindowSpectralKurtosis \n16 Spectral Irregularity K \t17\tcalcWindowSpectralIrregularityK \n17 Spectral Irregularity J \t18\tcalcWindowSpectralIrregularityJ \n18 Spectral Flatness \t\t19\tcalcWindowSpectralFlatness \n19 Spectral Tonality \t\t20\tcalcWindowSpectralTonality \n20 Spectral Min \t\t21\tcalcWindowSpectralMin \n21 Spectral Max \t\t22\tcalcWindowSpectralMax \n22 Spectral Crest \t\t23\tcalcWindowSpectralCrest \n23 Spectral Slope \t\t24\tcalcWindowSpectralSlope \n24 Spectral Spread \t\t25\tcalcWindowSpectralSpread \n25 Spectral Rolloff \t\t26\tcalcWindowSpectralRolloff \n26 Spectral HPS \t\t27\tcalcWindowSpectralHPS \n27 Spectral Loudness \t\t28\tcalcWindowSpectralLoudness \n28 Spectral Sharpness \t\t29\tcalcWindowSpectralSharpness \n29 Peak Tristimulus 1 \t\t31\tcalcWindowTristimulus1 \n30 Peak Tristimulus 2 \t\t32\tcalcWindowTristimulus2 \n31 Peak Tristimulus 3 \t\t33\tcalcWindowTristimulus3 \n32 MFCC \t\t\t40\tcalcWindowMFCC \n33 Bark \t\t\t41\tcalcWindowBark\n\n\n-----------\n\n\n\n1.7 Extracting Segmentations from a file using CAMEL\n-----------\nIn this section we are assuming you have adjusted the makefile and preprocessed the data as \nexplained above. Here we give a general explanation and some example code on segmenting and \nextracting some domain values from a PCM ASCII text file.\n\nThe simplest example of segmentation is to create a static segmentation of the file and\nextract a feature value of mean from each segment.\n\nFirst, as always, we make changes to the appropriate locations in the settings.txt file for\nsegmentation.  In the case of segmentation this generally means all the settings are fair\ngame depending on your needs.\n\nNext we create a simple main.cpp file.  In our main file we create a segmenter object and\ninitialise it with the PCM ASCII text file on which we are going to work with.  Next we\nrun the setup method for the segmentation object.  Then we call the run function on the \nsegmentation object telling it to extract feature 1 (mean) from segmentation method 2 (static \nby number of segments) and to make 10 segments.\n\nWe then get the results (a vector of 10 vectors, each containing the mean value for a segment)\nfor the extraction process using the getFeatureResults method and we get the position result\nusing the getPositionResults method.\n\n\n#include \"src/segmenter.h\"\n#include \u003cvector\u003e\nusing namespace std;\n\nint main(){\t \n\n\tSegmenter s(\"samplePCM.txt\");\n\ts.setup();\n\ts.run(1, 2, 10);\n\tvector\u003c vector\u003cdouble\u003e \u003e vvdFeatResults = s.getFeatureResults();\n\tvector\u003cint\u003e vviPosResults = s.getPositionResults();\t\n\n}\n\n-----------\n\n\n1.8 List of Segmentations in CAMEL (with identifiers for switch/settings)\n-----------\n\nSegmentation\t\tIdentifier\tFunction\nstaticBySize\t\t1\t\tstaticBySizeSegmentation\nstaticByNum\t\t2\t\tstaticByNumSegmentation\ntopkFarthestNeighbor\t3\t\ttopkFarthestNeighborSegmentation\ntopkLargestMatrixScore\t4\t\ttopkLargestMatrixScoreSegmentation\ngreedyMerge\t\t5\t\tgreedyMergeSegmentation\t\n\n\n-----------\n\n\n\n2. Extending CAMEL\n###########\n-----------\n\nCAMEL was also designed with simplified extension in mind.  It is relatively easy to \nadd new features, domains, and segmentation algorithms to CAMEL.  If you wish your \nextention to be added to the main version of CAMEL please contact the authors.\n\n-----------\n\n2.1 Adding a Domain to CAMEL\n-----------\n\nThere are of course several different things one might want to add into the domain class. This \nincludes a new windowing function, a new spectrum function, or a new domain all together.  We will\ndiscuss each of these here.\n\n2.1.1 Adding a window function\n\nAdding a new windowing function is extremely simple.  First create the function itself in the \ndomain.cpp. The return type should be a vector of doubles. This function should be written to \nevaluate over a single window of data passed in  as a vector of doubles (the only parameter). \nAny settings or parameters for this function beyond the vector can be added to the settings \nfile and be sourced via \n\n\tmySetting = settingsFile_.read\u003cmySettingType\u003e(\"MYSETTINGNAME\", mySettingDefaultValue);\n\nNext add the function prototype to the domain.h header file.  Next add a new switch to the \napplyWindowFunc() function in the domain.cpp class which references your new function. Finally\nuse the setting SPECTRUM_WINDOW in the settings file to select your new method by its switch\nvalue\n\n2.1.2 Adding a spectrum function\n\nAdding a new spectrum function is very similar to adding a new window function.  First create\na new function in the domain.cpp class for your spectrum where the only parameter is a vector\nof the type you expect to calculate over (FFT values would be a vector of double).  As a return \nvalue set it to a vector of doubles. For any settings which are required beyond the parameter\nvector use the settings file as explained abive under windowing functions.\n\nNext add the function prototype to the domain.h header file.  Then add a new switch to the \napplySpectrumFunc() function in the domain.cpp class which references your new function. Finally\nuse the setting SPECTRUM_TYPE in the settings file to select your new method by its swith value.\n\n\n2.1.3 Adding a new domain\n\nAdding a new domain is also simple (assuming it is calculated of the time domain, spectral domain,\nFFT, or the peak domain).\n\nAs with windows and spectrums assume that you are writing a function only concerned with calculating\nyour domain over a single vector of values (ints if its off the time domain, double for all else).\nYour only parameter should be that vector. All other settings should be dealt with as above. Your \nfunction should return a vector of ints or doubles.\n\nNext add the function prototype to the domain.h header file.  Source your function directly as seen\nabove in the examples on usage or add it to the featureExtract.cpp class for calculating/extracting\nfeatures over it (create a avgOverYOURDOMAINWindow function following the same methods as the others\nin the featureExtract class and then add it to the featureExtract switch).\n\n\n-----------\n\n2.2 Adding a Feature to CAMEL\n-----------\n\nAdding a feature to CAMEL is extremely simple.  For the sake of simplicity we will assume you are\nadding a feature over one of the domains already built into the system, otherwise simply see the\nadding a new domain section first.\n\nThe first step is to add the statistical feature calculation to the feature.cpp file.  Just \nwrite the function to calculate the feature over a single vector of the correct domain values.  Your \nreturn type should be either a single value (cast it to a double if its not already) or an array of \ndoubles (if it returns multi dimensionals like MFCC).  Your only parameter should be the vector \nof domain values.  Any other settings should use the settingsfile method outlined above in the \nadding a domain section.\n\nNext add the prototype to the feature.h header file.  The add a switch to your feature in the \nfeatureExtract.cpp getFeature() function.  Note use the correct avgOverDomainWindow function and \npass your feature to it as a pointer... see the other switch cases for examples.  You can now source\nyour feature directly as in the extracting a feature example above, or through segmentation.\n\n\n-----------\n\n2.3 Adding a Segmentation to CAMEL\n-----------\n\nAdding a segmentation algorithm to CAMEL simply involves creating a function in the \nsegmenter.cpp file.  Note your parameters can fluctuate here but by standard they should be\ntwo values: the number of segments, and the feature extraction method to process on. All other \nsettings should be collected from the settings.txt system described above.\n\nOnce you have added your segmentation algorithms function, add its prototype to the segmentation.h \nheader file and add a switch to it in the run() function of the segmentation class.  Most of the \nsegmentation functions in segmenter.cpp make use of several of the other functions (such as the\nsegmentGivenPositionsVector() function which given a vector of integer positions returns fills the\nresults vectors for both positions and feature values).\n\nYou can now source your segmentation function as explained above.\n\n\n\n-----------\n\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcbefus%2Fcamel-a-framework-for-audio-analysis","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcbefus%2Fcamel-a-framework-for-audio-analysis","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcbefus%2Fcamel-a-framework-for-audio-analysis/lists"}