README
1ctronome v0.5.6
2
3GNU/GPL copying rules apply, see COPYING
4
5DISCLAIMER
6 THIS SOFTWARE COMES AS-IS. ALTHOUGH THE AUTHOR DOES ITS BEST TO MAKE
7 THIS PROGRAM SAFE TO USE, MISTAKE HAPPENS. USE IT AT YOUR OWN RISK.
8
9 THE AUTHOR DOES NOT TAKE ANY RESPONSIBILITY FOR WHAT THIS SOFTWARE
10 DOES TO YOUR PC. BACKUP FREQUENTLY.
11
12INTRODUCTION
13 Ctronome is a very-very simple programmable metronome for Linux console,
14 with /dev/dsp (OSS) audio output. BPM ranges from 30 to 250, tacts like 3/4, 7/8
15 etc. are possible. It plays external WAV files, so one could use custom
16 sound samples.
17
18 Aim is to keep it as simple as it can be so dummies like me may understand
19 and modify it. (The source code looks ugly though;)
20
21 Non-OSS sound systems may need additonal utils/libraries to
22 provide OSS compatibility.
23
24
25COMPILE-TIME CONFIGURATION:
26 edit ctronome.h for defaults, the most important ones are:
27 metronomewav1 = "/usr/share/ctronome/metronome1.wav\0";
28 metronomewav2 = "/usr/share/ctronome/metronome2.wav\0";
29 dspdev = "/dev/dsp\0";
30
31 They speak for themselves.
32
33COMPILATION:
34 Only the very basic C libraries are needed that I believe to exist
35 on virtally all Linuxes. You need to have Linux kernel header
36 files installed (they come with the Linux kernel source), and OSS
37 (or OSS compatible) soundcard support.
38
39 Go into ctronome source directory and type 'make'.
40 It should compile whithout errors.
41
42INSTALLATION:
43 Ctronome is a single binary. You can put it anywhere you want in
44 your local or remote filesystem. You need two, preferably short
45 WAV files as metronome sample, put in the place you specified in
46 ctronome.h, or specified on the command line.
47
48 There are two one-channel and two two-channel (both channels are the same)
49 wav samples included, recorded from a real metronome. You have to install the one that
50 fits your sound system (see NOTES).
51
52 Example compilation and installation into default location:
53 tar xzf ctronome-0.5.6.tar.gz
54 cd ctronome-0.5.6
55 make
56 mkdir /usr/share/ctronome
57 cp *wav /usr/share/ctronome
58 cp ctronome /usr/local/bin
59
60RUNNING:
61 ctronome -b <bpm> -t <bpt> -c <count> -w1 <wav1> -w2 <wav2> -d <dsp_device> \
62 -p <program> -h -v
63 -b <bpm> beat per minute default: 60/4, range: 30-250/1-20
64 -t <bpt> beat per tact default: 1/4, range: 1-50/1-50
65 -p <filename> program file
66 -c <count> play tact/program <count> times then exit
67 -w1 <filename> wav to use for first beat of tact
68 default: /usr/share/ctronome/metronome1.wav
69 -w2 <filename> wav to use for other beat of tact
70 default: /usr/share/ctronome/metronome2.wav
71 -d <device> dsp device, default /dev/dsp
72 -h display help screen
73 -debug display debug messages
74
75 See prog_example.txt to learn how to program ctronome.
76
77 For BPM you can specify the base note. E.g. 60/4 means:
78 60 1/4 notes per minute -> length of 1/4 note is 1 second.
79
80 For BPT you can also define the base note. E.g. 4/4 means:
81 4 1/4 notes per tact -> length of a tact is 4 seconds.
82
83 As you can see, it is now possible to specify the BPM in 1/4 notes,
84 and then you can use BPT like 7/8, ctronome calculates lenght of 1/8 note
85 (which is half of the 1/4 in this example) and plays seven of them for a
86 tact.
87
88 If the base note for BPM is not specified, it defaults to the base note
89 of the tact.
90
91 It requires two 16 bit per sample WAV format, mono or stereo, and preferably
92 at least 44100Hz sample rate. *The two WAV formats must be the same!*
93 Please note that if your sound system does not support the exact format
94 provided by the WAV files, it will try its best to play it anyway, but
95 the result will be unpredictable. Debug mode will tell you the details.
96
97RUNNING ON SYSTEMS WITH PulseAudio:
98 On modern Linux distributions like Ubuntu 12.10 with PulseAudio, you may
99 experience the following error when running ctronome:
100 FATAL: cannot open dsp device /dev/dsp
101 /dev/dsp: No such file or directory
102
103 The solution is to either install OSS compatibility modules or install
104 the pulseaudio-utils package that contains a wrapper program called padsp.
105 Use this wrapper to run ctronome:
106
107 padsp ctronome <ctronome options>
108
109 Or you could use a simple shell script:
110 #!/bin/sh
111 padsp ctronome $@
112
113RUNNING ON SYSTEMS WITH ALSA:
114 An ALSA utility similar to PulseAudio's wrapper exists called aoss and is
115 part of alsa-oss package - at least in Debian-based distros.
116
117 aoss ctronome <ctronome options>
118
119RUNNING ON SYSTEMS WITHOUT OSS SUPPORT
120 As far as I know, Alsa and PulseAudio both have means to emulate OSS
121 either by installing compatibility modules or via a wrapper program.
122 Please refer to the documentation of the respective audio system.
123
124 If you have a step-by-step guide for a specific configuration, please
125 send it in and I will include it in the ctronome documentation.
126
127SEND BUGREPORTS TO:
128 ctronome at kign dot org
129
130CREDITS:
131 dsp code is based on gTick by Alex Roberts <bse@dial.pipex.com>,
132 and also the OSS Programmers Guide
133
134 Patch to eliminate warnings with Gcc4, and included WAV samples digitally
135 remastered to be more pronounced and precise by Martin Tarenskeen.
136
137 Patch to fix amd64 platform bug by Dmitry Kazarov
138
139 and help from my friends: Zola & Arpy.
140
141