Mercurial > hg > cmdp
changeset 1:629262395647
Added some dosumentation
added .hginfo
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/.hgignore Wed Feb 17 14:43:35 2016 +0000 @@ -0,0 +1,6 @@ +syntax: glob +*.class +re:^bin/uk/ac/qmul/eecs/depic/daw/haptics/ +re:^bin/uk/ac/qmul/eecs/depic/daw/beads/sonification/ +re:^bin/uk/ac/qmul/eecs/depic/daw/gui/actions/ +re:^bin/uk/ac/qmul/eecs/depic/daw/test/audio/
--- a/src/uk/ac/qmul/eecs/depic/daw/AudioLoader.java Wed Aug 26 16:16:53 2015 +0100 +++ b/src/uk/ac/qmul/eecs/depic/daw/AudioLoader.java Wed Feb 17 14:43:35 2016 +0000 @@ -33,8 +33,12 @@ import javax.swing.SwingWorker; import uk.ac.qmul.eecs.depic.daw.AudioLoader.ReturnObject; -import uk.ac.qmul.eecs.depic.daw.beads.BeadsSampleWrapper; +/** + * + * A swing worker that loads an audio file in a separate thread. It returns a RetunObject when the loading is complete. + * + */ public class AudioLoader extends SwingWorker<ReturnObject,Void>{ public static final int FILE_LOAD_TOTAL_PROGRESS = 100; /** @@ -157,12 +161,9 @@ } /* open the Sample for playback */ - BeadsSampleWrapper sample = new BeadsSampleWrapper(new - net.beadsproject.beads.data.Sample( - audioFile.getAbsolutePath(), - net.beadsproject.beads.data.Sample.Regime.newStreamingRegimeWithAging(1000, 1000) - ) - ); + Sample sample = Daw.getSoundEngineFactory().createSample(audioFile.getAbsolutePath()); + + /* return sample and chunks to the event dispatching thread */ return new ReturnObject(newFileChunks,sample,originalAudioFormat,conversionFormat); } @@ -171,8 +172,14 @@ return DEFAULT_CONVERSION_FORMAT; } + /** + * + * An object returned by the AudioLoader. It contains meta data about the sound sample such as wave peaks and format + * as well as the Sample object representing the loaded sample. + * + */ public static class ReturnObject { - public ReturnObject(WavePeaks peaks, BeadsSampleWrapper s, + public ReturnObject(WavePeaks peaks, Sample s, AudioFormat originalFormat, AudioFormat conversionFormat) { super(); this.peaks = peaks; @@ -182,7 +189,7 @@ } public WavePeaks peaks; - public BeadsSampleWrapper sample; + public Sample sample; public AudioFormat originalFormat; public AudioFormat conversionFormat; }
--- a/src/uk/ac/qmul/eecs/depic/daw/Automation.java Wed Aug 26 16:16:53 2015 +0100 +++ b/src/uk/ac/qmul/eecs/depic/daw/Automation.java Wed Feb 17 14:43:35 2016 +0000 @@ -24,6 +24,11 @@ import uk.ac.qmul.eecs.depic.patterns.Sequence; import uk.ac.qmul.eecs.depic.patterns.SequenceListener; +/** + * + * An automation in a DAW. Extends Sequence which is an abstraction of an automation. + * + */ public interface Automation extends Sequence { /** * Adds a new {@code AutomationValue} object to this automation.
--- a/src/uk/ac/qmul/eecs/depic/daw/Chunk.java Wed Aug 26 16:16:53 2015 +0100 +++ b/src/uk/ac/qmul/eecs/depic/daw/Chunk.java Wed Feb 17 14:43:35 2016 +0000 @@ -21,7 +21,13 @@ import uk.ac.qmul.eecs.depic.patterns.MathUtils; import uk.ac.qmul.eecs.depic.patterns.Range; - +/** + * + * A Chunk is a number of contiguous samples. It is used in the visual representation of a sound wave where only the maximum + * and minimum values of all the samples are taken into account. In the sound wave a chuck would be drawn as a vertical + * line at a specific x position, all the contiguous chunks make the sound wave as usually drawn. + * + */ public class Chunk extends Range<Float> { public static final Chunk SILENCE = new Chunk((short)0,(short)0); private float normalizedStart;
--- a/src/uk/ac/qmul/eecs/depic/daw/Clip.java Wed Aug 26 16:16:53 2015 +0100 +++ b/src/uk/ac/qmul/eecs/depic/daw/Clip.java Wed Feb 17 14:43:35 2016 +0000 @@ -20,7 +20,13 @@ import uk.ac.qmul.eecs.depic.patterns.Range; - +/** + * + * A Clip is a piece of audio Sample. Clips representing different parts of the same audio sample all share + * a reference to the same Sample. This way manipulating clips doesn't involve manipulating all the samples but + * just references to them. + * + */ public class Clip extends Range<Integer> implements Comparable<Clip> { private Sample sample; private int sampleStart;
--- a/src/uk/ac/qmul/eecs/depic/daw/ClipList.java Wed Aug 26 16:16:53 2015 +0100 +++ b/src/uk/ac/qmul/eecs/depic/daw/ClipList.java Wed Feb 17 14:43:35 2016 +0000 @@ -26,6 +26,11 @@ import java.util.List; import java.util.Map; +/** + * + * A list of Clips + * + */ public class ClipList extends ArrayList<Clip> { private static final long serialVersionUID = 1L; private int scaleFactor;
--- a/src/uk/ac/qmul/eecs/depic/daw/Daw.java Wed Aug 26 16:16:53 2015 +0100 +++ b/src/uk/ac/qmul/eecs/depic/daw/Daw.java Wed Feb 17 14:43:35 2016 +0000 @@ -23,6 +23,11 @@ import uk.ac.qmul.eecs.depic.daw.beads.BeadsSoundEngineFactory; import uk.ac.qmul.eecs.depic.daw.gui.MainFrame; +/** + * + * Entry point for the program + * + */ public class Daw implements Runnable{ private static SoundEngineFactory soundEngineFactory;
--- a/src/uk/ac/qmul/eecs/depic/daw/DbWave.java Wed Aug 26 16:16:53 2015 +0100 +++ b/src/uk/ac/qmul/eecs/depic/daw/DbWave.java Wed Feb 17 14:43:35 2016 +0000 @@ -26,6 +26,11 @@ import uk.ac.qmul.eecs.depic.patterns.Sequence; import uk.ac.qmul.eecs.depic.patterns.SequenceListener; +/** + * + * A Wave that displays chucks in DB scale + * + */ public class DbWave implements Wave { private Wave soundWave ; private Sequence peakLevelSequence;
--- a/src/uk/ac/qmul/eecs/depic/daw/Parameter.java Wed Aug 26 16:16:53 2015 +0100 +++ b/src/uk/ac/qmul/eecs/depic/daw/Parameter.java Wed Feb 17 14:43:35 2016 +0000 @@ -20,6 +20,11 @@ import uk.ac.qmul.eecs.depic.patterns.Range; +/** + * + * A parameter of the audio computation + * + */ public interface Parameter { public interface Type { String getLabel();
--- a/src/uk/ac/qmul/eecs/depic/daw/ParametersControl.java Wed Aug 26 16:16:53 2015 +0100 +++ b/src/uk/ac/qmul/eecs/depic/daw/ParametersControl.java Wed Feb 17 14:43:35 2016 +0000 @@ -18,7 +18,11 @@ */ package uk.ac.qmul.eecs.depic.daw; - +/** + * + * The control class of all parameters. There is one Control for each SoundWave. + * + */ public interface ParametersControl { Parameter getGainParameter();
--- a/src/uk/ac/qmul/eecs/depic/daw/Sample.java Wed Aug 26 16:16:53 2015 +0100 +++ b/src/uk/ac/qmul/eecs/depic/daw/Sample.java Wed Feb 17 14:43:35 2016 +0000 @@ -18,7 +18,11 @@ */ package uk.ac.qmul.eecs.depic.daw; - +/** + * + * An Audio Sample + * + */ public interface Sample { public int getBytesPerSample();
--- a/src/uk/ac/qmul/eecs/depic/daw/Selection.java Wed Aug 26 16:16:53 2015 +0100 +++ b/src/uk/ac/qmul/eecs/depic/daw/Selection.java Wed Feb 17 14:43:35 2016 +0000 @@ -20,7 +20,11 @@ import uk.ac.qmul.eecs.depic.patterns.Range; - +/** + * + * A selection on integer values + * + */ public final class Selection extends Range<Integer>{ public static Selection ZERO_SELECTION = new Selection(0,1); private int scaleFactor;
--- a/src/uk/ac/qmul/eecs/depic/daw/Sonification.java Wed Aug 26 16:16:53 2015 +0100 +++ b/src/uk/ac/qmul/eecs/depic/daw/Sonification.java Wed Feb 17 14:43:35 2016 +0000 @@ -20,6 +20,13 @@ import uk.ac.qmul.eecs.depic.patterns.SequenceMapping; +/** + * + * A Sonification object. It represents information as sound. This is used both for playing samples + * in response to a user action and for giving a sonic representation of DAW entities such as automations + * through the SequenceMapping abstraction. + * + */ public interface Sonification { public SequenceMapping getSequenceMapping(SoundType soundType);
--- a/src/uk/ac/qmul/eecs/depic/daw/Sound.java Wed Aug 26 16:16:53 2015 +0100 +++ b/src/uk/ac/qmul/eecs/depic/daw/Sound.java Wed Feb 17 14:43:35 2016 +0000 @@ -21,6 +21,11 @@ import java.beans.PropertyChangeListener; import java.beans.PropertyChangeSupport; +/** + * + * a sound played by the Sonification + * + */ public class Sound { private Enum<?> type; private float pan;
--- a/src/uk/ac/qmul/eecs/depic/daw/SoundEngineFactory.java Wed Aug 26 16:16:53 2015 +0100 +++ b/src/uk/ac/qmul/eecs/depic/daw/SoundEngineFactory.java Wed Feb 17 14:43:35 2016 +0000 @@ -18,11 +18,17 @@ */ package uk.ac.qmul.eecs.depic.daw; - +/** + * + * Interface implemented by the sound engine package. This provides all the sound services in an abstract way. + * + */ public interface SoundEngineFactory { public SoundWave createSoundWave(); public Parameter createParameter(Parameter.Type type, SoundWave wave); public Sonification getSharedSonification(); + + public Sample createSample(String fileAbsolutePath) throws Exception; }
--- a/src/uk/ac/qmul/eecs/depic/daw/SoundType.java Wed Aug 26 16:16:53 2015 +0100 +++ b/src/uk/ac/qmul/eecs/depic/daw/SoundType.java Wed Feb 17 14:43:35 2016 +0000 @@ -18,6 +18,11 @@ */ package uk.ac.qmul.eecs.depic.daw; +/** + * + * Type of sounds that are triggered by the sonification in response to events + * + */ public enum SoundType { HAPTIC_PORT_TOUCH, ERROR,
--- a/src/uk/ac/qmul/eecs/depic/daw/SoundWave.java Wed Aug 26 16:16:53 2015 +0100 +++ b/src/uk/ac/qmul/eecs/depic/daw/SoundWave.java Wed Feb 17 14:43:35 2016 +0000 @@ -24,6 +24,11 @@ import javax.swing.JComponent; +/** + * + * A sound wave, the usual artifact used to represent audio visually + * + */ public interface SoundWave extends Wave { public static final String FILE_ERROR_PROPERTY = "FILE_ERROR_PROPERTY";
--- a/src/uk/ac/qmul/eecs/depic/daw/SoundWaveEditor.java Wed Aug 26 16:16:53 2015 +0100 +++ b/src/uk/ac/qmul/eecs/depic/daw/SoundWaveEditor.java Wed Feb 17 14:43:35 2016 +0000 @@ -18,6 +18,12 @@ */ package uk.ac.qmul.eecs.depic.daw; +/** + * + * An editor for the sound wave with all the usual edit actions. This is an abstract interface that must be implemented + * by a concrete class of the sound engine package. + * + */ public interface SoundWaveEditor { public boolean cut(SoundWave wave, Selection s);
--- a/src/uk/ac/qmul/eecs/depic/daw/SoundWaveEvent.java Wed Aug 26 16:16:53 2015 +0100 +++ b/src/uk/ac/qmul/eecs/depic/daw/SoundWaveEvent.java Wed Feb 17 14:43:35 2016 +0000 @@ -20,6 +20,11 @@ import java.util.EventObject; +/** + * + * An event observed by SoundWaveListeners + * + */ public class SoundWaveEvent extends EventObject { private static final long serialVersionUID = 1L; private Object args;
--- a/src/uk/ac/qmul/eecs/depic/daw/SoundWaveListener.java Wed Aug 26 16:16:53 2015 +0100 +++ b/src/uk/ac/qmul/eecs/depic/daw/SoundWaveListener.java Wed Feb 17 14:43:35 2016 +0000 @@ -18,6 +18,11 @@ */ package uk.ac.qmul.eecs.depic.daw; +/** + * + * Observer of a Sound Wave + * + */ public interface SoundWaveListener { public void update(SoundWaveEvent evt); }
--- a/src/uk/ac/qmul/eecs/depic/daw/Wave.java Wed Aug 26 16:16:53 2015 +0100 +++ b/src/uk/ac/qmul/eecs/depic/daw/Wave.java Wed Feb 17 14:43:35 2016 +0000 @@ -20,6 +20,11 @@ import uk.ac.qmul.eecs.depic.patterns.Sequence; +/** + * + * An abstract wave + * + */ public interface Wave { public int getChunkNum();
--- a/src/uk/ac/qmul/eecs/depic/daw/WavePeaks.java Wed Aug 26 16:16:53 2015 +0100 +++ b/src/uk/ac/qmul/eecs/depic/daw/WavePeaks.java Wed Feb 17 14:43:35 2016 +0000 @@ -21,7 +21,11 @@ import java.util.ArrayList; import java.util.List; - +/** + * + * a list of list of chunks corresponding to peaks in the sound wave. One list for each possible scaling factor. + * + */ public class WavePeaks extends ArrayList<List<Chunk>> { private static final long serialVersionUID = 1L; private boolean constructed;
--- a/src/uk/ac/qmul/eecs/depic/daw/beads/BeadsSampleWrapper.java Wed Aug 26 16:16:53 2015 +0100 +++ b/src/uk/ac/qmul/eecs/depic/daw/beads/BeadsSampleWrapper.java Wed Feb 17 14:43:35 2016 +0000 @@ -20,6 +20,12 @@ import uk.ac.qmul.eecs.depic.daw.Sample; +/** + * + * wraps a net.beadsproject.beads.data.Sample into a uk.ac.qmul.eecs.depic.daw.Sample so that the former + * can be used as the latter in the uk.ac.qmul.eecs.depic.daw package. + * + */ public class BeadsSampleWrapper implements Sample { private net.beadsproject.beads.data.Sample delegate;
--- a/src/uk/ac/qmul/eecs/depic/daw/beads/BeadsSoundEngineFactory.java Wed Aug 26 16:16:53 2015 +0100 +++ b/src/uk/ac/qmul/eecs/depic/daw/beads/BeadsSoundEngineFactory.java Wed Feb 17 14:43:35 2016 +0000 @@ -18,8 +18,13 @@ */ package uk.ac.qmul.eecs.depic.daw.beads; +import java.io.IOException; + +import javax.sound.sampled.UnsupportedAudioFileException; + import uk.ac.qmul.eecs.depic.daw.Parameter; import uk.ac.qmul.eecs.depic.daw.Parameter.Type; +import uk.ac.qmul.eecs.depic.daw.Sample; import uk.ac.qmul.eecs.depic.daw.Sonification; import uk.ac.qmul.eecs.depic.daw.SoundEngineFactory; import uk.ac.qmul.eecs.depic.daw.SoundWave; @@ -70,5 +75,14 @@ public Sonification getSharedSonification() { return sonification; } + + @Override + public Sample createSample(String fileAbsolutePath) throws Exception { + return new BeadsSampleWrapper(new net.beadsproject.beads.data.Sample( + fileAbsolutePath, + net.beadsproject.beads.data.Sample.Regime.newStreamingRegimeWithAging(1000, 1000) + ) + ); + } }
--- a/src/uk/ac/qmul/eecs/depic/daw/beads/BeadsSoundWave.java Wed Aug 26 16:16:53 2015 +0100 +++ b/src/uk/ac/qmul/eecs/depic/daw/beads/BeadsSoundWave.java Wed Feb 17 14:43:35 2016 +0000 @@ -493,7 +493,7 @@ /* sample player for listening to the sample */ samplePlayer.pause(true); - GranularPlayer granular = new GranularPlayer(ac,returnObject.sample); + GranularPlayer granular = new GranularPlayer(ac,(BeadsSampleWrapper) returnObject.sample); granulars.add(granular); /* adds the ugen to the master gain */ ((UGen)parametersControl.getParameter(Parameter.GAIN_TYPE)).addInput(granular);
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/src/uk/ac/qmul/eecs/depic/daw/beads/package-info.java Wed Feb 17 14:43:35 2016 +0000 @@ -0,0 +1,10 @@ +/** + * An implementation of the sound engine that uses the Beads library (http://www.beadsproject.net) + * + * this package contains the classes that handle sound intended as content: playing back a sound files with automations + * applied etc. + * + * For the sonification part look in uk.ac.qmul.eecs.depic.daw.beads.sonification + */ + +package uk.ac.qmul.eecs.depic.daw.beads; \ No newline at end of file
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/src/uk/ac/qmul/eecs/depic/daw/beads/sonification/package-info.java Wed Feb 17 14:43:35 2016 +0000 @@ -0,0 +1,11 @@ +/** + * The part of the sound engine that concerns the sonification. + * + * The sonification can be of two types : + * <ul> + * <li> playing samples when an event occurs (e.g. the user creates a new automation point) </li> + * <li> playing the sonic representation of an entity of the DAW (e.g. an automation) </li> + * </ul> + */ + +package uk.ac.qmul.eecs.depic.daw.beads.sonification; \ No newline at end of file
--- a/src/uk/ac/qmul/eecs/depic/daw/gui/AudioTrack.java Wed Aug 26 16:16:53 2015 +0100 +++ b/src/uk/ac/qmul/eecs/depic/daw/gui/AudioTrack.java Wed Feb 17 14:43:35 2016 +0000 @@ -48,7 +48,7 @@ import uk.ac.qmul.eecs.depic.patterns.SequenceMapping; /** - * + * An audio track widget. * * *
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/src/uk/ac/qmul/eecs/depic/daw/package-info.java Wed Feb 17 14:43:35 2016 +0000 @@ -0,0 +1,21 @@ +/** + * + * This package contains the core data of the program. The data model as in the Model-View-Control paradigm + * It abstracts over the sound engine, that is it provides an abstract interface over the specific sound engine + * so that it can be reused with other audio systems. The SoundEnfingeFactory class is the entry point for a + * any sound engine package. The entry point for the sound engine is {@code Daw.getSoundEngineFactory()} + * so you'd need to modify that call to make your own sound engine. + * + * As per the faced design pattern all the functionality of a sound engine package would be attained by + * providing an implementation of the {@code SoundEngineFactory} factory interface and of, the interface types + * returned by its methods (SoundWave, Parameter, Sonification and Sample) and by SoundWave's methods. + * + * A default sound engine is provided using the Beads library (see uk.ac.qmul.eecs.depic.daw.beads package). + * + * + * + * + * + * + */ +package uk.ac.qmul.eecs.depic.daw; \ No newline at end of file
--- a/src/uk/ac/qmul/eecs/depic/patterns/MathUtils.java Wed Aug 26 16:16:53 2015 +0100 +++ b/src/uk/ac/qmul/eecs/depic/patterns/MathUtils.java Wed Feb 17 14:43:35 2016 +0000 @@ -18,7 +18,7 @@ */ package uk.ac.qmul.eecs.depic.patterns; - +/** Utilities for math operations */ public class MathUtils { public static boolean equal(float a, float b){ @@ -57,7 +57,11 @@ return (float) (Math.pow(10, db/ 20.0)); } - + /** + * + * Scales a float from one range of values to another. The scaling can be either lineas or exponential. + * + */ public static class Scale { private Range<java.lang.Float> from; private Range<java.lang.Float> to;
--- a/src/uk/ac/qmul/eecs/depic/patterns/Range.java Wed Aug 26 16:16:53 2015 +0100 +++ b/src/uk/ac/qmul/eecs/depic/patterns/Range.java Wed Feb 17 14:43:35 2016 +0000 @@ -21,6 +21,7 @@ /** * * Immutable class containing two comparable number which represent the start and the end of a range. + * * * @param <T> */
--- a/src/uk/ac/qmul/eecs/depic/patterns/SequenceEvent.java Wed Aug 26 16:16:53 2015 +0100 +++ b/src/uk/ac/qmul/eecs/depic/patterns/SequenceEvent.java Wed Feb 17 14:43:35 2016 +0000 @@ -20,10 +20,19 @@ import java.util.EventObject; - +/** + * + * An event in a sequence. Objects of this type are passed to the listeners of a sequence when it get changed. + * + */ public class SequenceEvent extends EventObject{ private static final long serialVersionUID = 1L; + /** + * + * Type of events in a sequence + * + */ public enum What { VALUE_ADDED, VALUE_REMOVED,
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/src/uk/ac/qmul/eecs/depic/patterns/package-info.java Wed Feb 17 14:43:35 2016 +0000 @@ -0,0 +1,19 @@ +/** + * This package contains classes that abstract DAW entities, such as automations + * and sequences of wave peak points, into more general interfaces that can be reused in other context. + * Possibly also unrelated to DAW. + * + * Automation lines for example, are just sequences of connected values (automation points) scattered in time and + * the values can only be within a certain range. + * This is common to many graphs in other domains that display ranged values over time. + * So the idea behind this package is to provide software support to design pattern reusability over different domains. + * A sonification or a haptic display strategy that works in one domain can be easily reused in another domain + * just by implementing a bunch of interfaces. + * + * So in this program, the audio-haptic display is done in terms of the abstract interfaces of this package rather than in terms + * of the DAW specific Java classes, like {@code Automation} or {@code AutomationValue}. + * Obviously these implements such interfaces. + * + */ + +package uk.ac.qmul.eecs.depic.patterns; \ No newline at end of file