octave_packages/audio-1.1.4/doc-cache

   1 # Created by Octave 3.6.1, Tue Mar 20 07:03:19 2012 UTC <root@t61>
   2 # name: cache
   3 # type: cell
   4 # rows: 3
   5 # columns: 7
   6 # name: <cell-element>
   7 # type: sq_string
   8 # elements: 1
   9 # length: 2
  10 au
  11
  12
  13 # name: <cell-element>
  14 # type: sq_string
  15 # elements: 1
  16 # length: 315
  17  y = au(x, fs, lo [, hi])
  18
  19  Extract data from x for time range lo to hi in milliseconds.  If lo
  20  is [], start at the beginning.  If hi is [], go to the end.  If hi is
  21  not specified, return the single element at lo.  If lo<0, prepad the
  22  signal to time lo.  If hi is beyond the end, postpad the signal to
  23  time hi.
  24
  25
  26
  27 # name: <cell-element>
  28 # type: sq_string
  29 # elements: 1
  30 # length: 26
  31  y = au(x, fs, lo [, hi])
  32
  33
  34
  35
  36 # name: <cell-element>
  37 # type: sq_string
  38 # elements: 1
  39 # length: 6
  40 auload
  41
  42
  43 # name: <cell-element>
  44 # type: sq_string
  45 # elements: 1
  46 # length: 1008
  47  -- Function File: [X,FS,SAMPLEFORMAT] = auload (FILENAME)
  48      Reads an audio waveform from a file given by the string FILENAME.
  49      Returns the audio samples in data, one column per channel, one row
  50      per time slice.  Also returns the sample rate and stored format
  51      (one of ulaw, alaw, char, int16, int24, int32, float, double). The
  52      sample value will be normalized to the range [-1,1] regardless of
  53      the stored format.
  54
  55              [x, fs] = auload(file_in_loadpath("sample.wav"));
  56              auplot(x,fs);
  57
  58      Note that translating the asymmetric range [-2^n,2^n-1] into the
  59      symmetric range [-1,1] requires a DC offset of 2/2^n. The inverse
  60      process used by ausave requires a DC offset of -2/2^n, so loading
  61      and saving a file will not change the contents.  Other
  62      applications may compensate for the asymmetry in a different way
  63      (including previous versions of auload/ausave) so you may find
  64      small differences in calculated DC offsets for the same file.
  65
  66
  67
  68
  69 # name: <cell-element>
  70 # type: sq_string
  71 # elements: 1
  72 # length: 65
  73 Reads an audio waveform from a file given by the string FILENAME.
  74
  75
  76
  77 # name: <cell-element>
  78 # type: sq_string
  79 # elements: 1
  80 # length: 6
  81 auplot
  82
  83
  84 # name: <cell-element>
  85 # type: sq_string
  86 # elements: 1
  87 # length: 2310
  88  -- Function File: [Y,T,SCALE] =  auplot (X)
  89  -- Function File: [Y,T,SCALE] =  auplot (X,FS)
  90  -- Function File: [Y,T,SCALE] =  auplot (X,FS,OFFSET)
  91  -- Function File: [Y,T,SCALE] =  auplot (...,PLOTSTR)
  92      Plot the waveform data, displaying time on the X axis.  If you are
  93      plotting a slice from the middle of an array, you may want to
  94      specify the OFFSET into the array to retain the appropriate time
  95      index. If the waveform contains multiple channels, then the data
  96      are scaled to the range [-1,1] and shifted so that they do not
  97      overlap. If a PLOTSTR is given, it is passed as the third argument
  98      to the plot command. This allows you to set the linestyle easily.
  99      FS defaults to 8000 Hz, and OFFSET defaults to 0 samples.
 100
 101      Instead of plotting directly, you can ask for the returned
 102      processed vectors. If Y has multiple channels, the plot should
 103      have the y-range [-1 2*size(y,2)-1]. scale specifies how much the
 104      matrix was scaled so that each signal would fit in the specified
 105      range.
 106
 107      Since speech samples can be very long, we need a way to plot them
 108      rapidly. For long signals, auplot windows the data and keeps the
 109      minimum and maximum values in the window.  Together, these values
 110      define the minimal polygon which contains the signal.  The number
 111      of points in the polygon is set with the global variable
 112      auplot_points.  The polygon may be either 'filled' or 'outline',
 113      as set by the global variable auplot_format.  For moderately long
 114      data, the window does not contain enough points to draw an
 115      interesting polygon. In this case, simply choosing an arbitrary
 116      point from the window looks best.  The global variable
 117      auplot_window sets the size of the window required for creating
 118      polygons.  You can turn off the polygons entirely by setting
 119      auplot_format to 'sampled'.  To turn off fast plotting entirely,
 120      set auplot_format to 'direct', or set auplot_points=1. There is no
 121      reason to do this since your screen resolution is limited and
 122      increasing the number of points plotted will not add any
 123      information.  auplot_format, auplot_points and auplot_window may
 124      be set in .octaverc.  By default auplot_format is 'outline',
 125      auplot_points=1000 and auplot_window=7.
 126
 127
 128
 129
 130 # name: <cell-element>
 131 # type: sq_string
 132 # elements: 1
 133 # length: 54
 134 Plot the waveform data, displaying time on the X axis.
 135
 136
 137
 138 # name: <cell-element>
 139 # type: sq_string
 140 # elements: 1
 141 # length: 6
 142 ausave
 143
 144
 145 # name: <cell-element>
 146 # type: sq_string
 147 # elements: 1
 148 # length: 871
 149  usage: ausave('filename.ext', x, fs, format)
 150
 151  Writes an audio file with the appropriate header. The extension on
 152  the filename determines the layout of the header. Currently supports
 153  .wav and .au layouts.  Data is a matrix of audio samples in the
 154  range [-1,1] (inclusive), one row per time step, one column per
 155  channel. Fs defaults to 8000 Hz.  Format is one of ulaw, alaw, char,
 156  short, long, float, double
 157
 158  Note that translating the symmetric range [-1,1] into the asymmetric
 159  range [-2^n,2^n-1] requires a DC offset of -2/2^n.  The inverse
 160  process used by auload requires a DC offset of 2/2^n, so loading and
 161  saving a file will not change the contents.  Other applications may
 162  compensate for the asymmetry in a different way (including previous
 163  versions of auload/ausave) so you may find small differences in
 164  calculated DC offsets for the same file.
 165
 166
 167
 168 # name: <cell-element>
 169 # type: sq_string
 170 # elements: 1
 171 # length: 25
 172  usage: ausave('filename.
 173
 174
 175
 176 # name: <cell-element>
 177 # type: sq_string
 178 # elements: 1
 179 # length: 4
 180 clip
 181
 182
 183 # name: <cell-element>
 184 # type: sq_string
 185 # elements: 1
 186 # length: 206
 187  Clip values outside the range to the value at the boundary of the
 188  range.
 189
 190  X = clip(X)
 191    Clip to range [0, 1]
 192
 193  X = clip(X, hi)
 194    Clip to range [0, hi]
 195
 196  X = clip(X, [lo, hi])
 197    Clip to range [lo, hi]
 198
 199
 200
 201 # name: <cell-element>
 202 # type: sq_string
 203 # elements: 1
 204 # length: 74
 205  Clip values outside the range to the value at the boundary of the
 206  range.
 207
 208
 209
 210 # name: <cell-element>
 211 # type: sq_string
 212 # elements: 1
 213 # length: 5
 214 sound
 215
 216
 217 # name: <cell-element>
 218 # type: sq_string
 219 # elements: 1
 220 # length: 2377
 221  usage: sound(x [, fs, bs])
 222
 223  Play the signal through the speakers.  Data is a matrix with
 224  one column per channel.  Rate fs defaults to 8000 Hz.  The signal
 225  is clipped to [-1, 1].  Buffer size bs controls how many audio samples
 226  are clipped and buffered before sending them to the audio player.  bs
 227  defaults to fs, which is equivalent to 1 second of audio.
 228
 229  Note that if $DISPLAY != $HOSTNAME:n then a remote shell is opened
 230  to the host specified in $HOSTNAME to play the audio.  See manual
 231  pages for ssh, ssh-keygen, ssh-agent and ssh-add to learn how to
 232  set it up.
 233
 234  This function writes the audio data through a pipe to the program
 235  "play" from the sox distribution.  sox runs pretty much anywhere,
 236  but it only has audio drivers for OSS (primarily linux and freebsd)
 237  and SunOS.  In case your local machine is not one of these, write
 238  a shell script such as ~/bin/octaveplay, substituting AUDIO_UTILITY
 239  with whatever audio utility you happen to have on your system:
 240    #!/bin/sh
 241    cat > ~/.octave_play.au
 242    SYSTEM_AUDIO_UTILITY ~/.octave_play.au
 243    rm -f ~/.octave_play.au
 244  and set the global variable (e.g., in .octaverc)
 245    global sound_play_utility="~/bin/octaveplay";
 246
 247  If your audio utility can accept an AU file via a pipe, then you
 248  can use it directly:
 249    global sound_play_utility="SYSTEM_AUDIO_UTILITY flags"
 250  where flags are whatever you need to tell it that it is receiving
 251  an AU file.
 252
 253  With clever use of the command dd, you can chop out the header and
 254  dump the data directly to the audio device in big-endian format:
 255    global sound_play_utility="dd of=/dev/audio ibs=2 skip=12"
 256  or little-endian format:
 257    global sound_play_utility="dd of=/dev/dsp ibs=2 skip=12 conv=swab"
 258  but you lose the sampling rate in the process.
 259
 260  Finally, you could modify sound.m to produce data in a format that
 261  you can dump directly to your audio device and use "cat >/dev/audio"
 262  as your sound_play_utility.  Things you may want to do are resample
 263  so that the rate is appropriate for your machine and convert the data
 264  to mulaw and output as bytes.
 265
 266  If you experience buffer underruns while playing audio data, the bs
 267  buffer size parameter can be increased to tradeoff interactivity
 268  for smoother playback.  If bs=Inf, then all the data is clipped and
 269  buffered before sending it to the audio player pipe.  By default, 1
 270  sec of audio is buffered.
 271
 272
 273
 274 # name: <cell-element>
 275 # type: sq_string
 276 # elements: 1
 277 # length: 28
 278  usage: sound(x [, fs, bs])
 279
 280
 281
 282
 283 # name: <cell-element>
 284 # type: sq_string
 285 # elements: 1
 286 # length: 7
 287 soundsc
 288
 289
 290 # name: <cell-element>
 291 # type: sq_string
 292 # elements: 1
 293 # length: 793
 294  usage: soundsc(x, fs, limit) or soundsc(x, fs, [ lo, hi ])
 295
 296  soundsc(x)
 297     Scale the signal so that [min(x), max(x)] -> [-1, 1], then
 298     play it through the speakers at 8000 Hz sampling rate.  The
 299     signal has one column per channel.
 300
 301  soundsc(x,fs)
 302     Scale the signal and play it at sampling rate fs.
 303
 304  soundsc(x, fs, limit)
 305     Scale the signal so that [-|limit|, |limit|] -> [-1, 1], then
 306     play it at sampling rate fs.  If fs is empty, then the default
 307     8000 Hz sampling rate is used.
 308
 309  soundsc(x, fs, [ lo, hi ])
 310     Scale the signal so that [lo, hi] -> [-1, 1], then play it
 311     at sampling rate fs.  If fs is empty, then the default 8000 Hz
 312     sampling rate is used.
 313
 314  y=soundsc(...)
 315     return the scaled waveform rather than play it.
 316
 317  See sound for more information.
 318
 319
 320
 321 # name: <cell-element>
 322 # type: sq_string
 323 # elements: 1
 324 # length: 60
 325  usage: soundsc(x, fs, limit) or soundsc(x, fs, [ lo, hi ])
 326
 327
 328
 329
 330
 331