Mercurial > octave
annotate scripts/audio/soundsc.m @ 30568:82b685157e2b
doc: Update documentation in audio/ directory.
* __get_properties__.m, audioplayer.m, disp.m, get.m, isplaying.m, pause.m,
play.m, playblocking.m, resume.m, set.m, stop.m, subsasgn.m, subsref.m,
__get_properties__.m, audiorecorder.m, disp.m, get.m, getaudiodata.m,
getplayer.m, isrecording.m, pause.m, play.m, record.m, recordblocking.m,
resume.m, set.m, stop.m, subsasgn.m, subsref.m, record.m, sound.m, soundsc.m:
Re-write lots of documentation for clarity. Add @seealso links in @audioplayer
and @audiorecorder classes.
author | Rik <rik@octave.org> |
---|---|
date | Wed, 29 Dec 2021 18:17:53 -0800 |
parents | 796f54d4ddbf |
children | faf96757915a |
rev | line source |
---|---|
27923
bd51beb6205e
update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents:
27919
diff
changeset
|
1 ######################################################################## |
bd51beb6205e
update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents:
27919
diff
changeset
|
2 ## |
30564
796f54d4ddbf
update Octave Project Developers copyright for the new year
John W. Eaton <jwe@octave.org>
parents:
29359
diff
changeset
|
3 ## Copyright (C) 2016-2022 The Octave Project Developers |
27918
b442ec6dda5c
use centralized file for copyright info for individual contributors
John W. Eaton <jwe@octave.org>
parents:
26376
diff
changeset
|
4 ## |
27923
bd51beb6205e
update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents:
27919
diff
changeset
|
5 ## See the file COPYRIGHT.md in the top-level directory of this |
bd51beb6205e
update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents:
27919
diff
changeset
|
6 ## distribution or <https://octave.org/copyright/>. |
19682
c2478360291f
New functions sound and soundsc
Mike Miller <mtmiller@ieee.org>
parents:
diff
changeset
|
7 ## |
c2478360291f
New functions sound and soundsc
Mike Miller <mtmiller@ieee.org>
parents:
diff
changeset
|
8 ## This file is part of Octave. |
c2478360291f
New functions sound and soundsc
Mike Miller <mtmiller@ieee.org>
parents:
diff
changeset
|
9 ## |
24534
194eb4bd202b
maint: Update punctuation for GPL v3 license text.
Rik <rik@octave.org>
parents:
23220
diff
changeset
|
10 ## Octave is free software: you can redistribute it and/or modify it |
19682
c2478360291f
New functions sound and soundsc
Mike Miller <mtmiller@ieee.org>
parents:
diff
changeset
|
11 ## under the terms of the GNU General Public License as published by |
24534
194eb4bd202b
maint: Update punctuation for GPL v3 license text.
Rik <rik@octave.org>
parents:
23220
diff
changeset
|
12 ## the Free Software Foundation, either version 3 of the License, or |
22755
3a2b891d0b33
maint: Standardize Copyright formatting.
Rik <rik@octave.org>
parents:
22323
diff
changeset
|
13 ## (at your option) any later version. |
19682
c2478360291f
New functions sound and soundsc
Mike Miller <mtmiller@ieee.org>
parents:
diff
changeset
|
14 ## |
c2478360291f
New functions sound and soundsc
Mike Miller <mtmiller@ieee.org>
parents:
diff
changeset
|
15 ## Octave is distributed in the hope that it will be useful, but |
c2478360291f
New functions sound and soundsc
Mike Miller <mtmiller@ieee.org>
parents:
diff
changeset
|
16 ## WITHOUT ANY WARRANTY; without even the implied warranty of |
22755
3a2b891d0b33
maint: Standardize Copyright formatting.
Rik <rik@octave.org>
parents:
22323
diff
changeset
|
17 ## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
3a2b891d0b33
maint: Standardize Copyright formatting.
Rik <rik@octave.org>
parents:
22323
diff
changeset
|
18 ## GNU General Public License for more details. |
19682
c2478360291f
New functions sound and soundsc
Mike Miller <mtmiller@ieee.org>
parents:
diff
changeset
|
19 ## |
c2478360291f
New functions sound and soundsc
Mike Miller <mtmiller@ieee.org>
parents:
diff
changeset
|
20 ## You should have received a copy of the GNU General Public License |
c2478360291f
New functions sound and soundsc
Mike Miller <mtmiller@ieee.org>
parents:
diff
changeset
|
21 ## along with Octave; see the file COPYING. If not, see |
24534
194eb4bd202b
maint: Update punctuation for GPL v3 license text.
Rik <rik@octave.org>
parents:
23220
diff
changeset
|
22 ## <https://www.gnu.org/licenses/>. |
27923
bd51beb6205e
update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents:
27919
diff
changeset
|
23 ## |
bd51beb6205e
update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents:
27919
diff
changeset
|
24 ######################################################################## |
19682
c2478360291f
New functions sound and soundsc
Mike Miller <mtmiller@ieee.org>
parents:
diff
changeset
|
25 |
c2478360291f
New functions sound and soundsc
Mike Miller <mtmiller@ieee.org>
parents:
diff
changeset
|
26 ## -*- texinfo -*- |
20852
516bb87ea72e
2015 Code Sprint: remove class of function from docstring for all m-files.
Rik <rik@octave.org>
parents:
20158
diff
changeset
|
27 ## @deftypefn {} {} soundsc (@var{y}) |
516bb87ea72e
2015 Code Sprint: remove class of function from docstring for all m-files.
Rik <rik@octave.org>
parents:
20158
diff
changeset
|
28 ## @deftypefnx {} {} soundsc (@var{y}, @var{fs}) |
516bb87ea72e
2015 Code Sprint: remove class of function from docstring for all m-files.
Rik <rik@octave.org>
parents:
20158
diff
changeset
|
29 ## @deftypefnx {} {} soundsc (@var{y}, @var{fs}, @var{nbits}) |
516bb87ea72e
2015 Code Sprint: remove class of function from docstring for all m-files.
Rik <rik@octave.org>
parents:
20158
diff
changeset
|
30 ## @deftypefnx {} {} soundsc (@dots{}, [@var{ymin}, @var{ymax}]) |
19682
c2478360291f
New functions sound and soundsc
Mike Miller <mtmiller@ieee.org>
parents:
diff
changeset
|
31 ## Scale the audio data @var{y} and play it at sample rate @var{fs} to the |
20158
7503499a252b
doc: Update docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents:
19833
diff
changeset
|
32 ## default audio device. |
7503499a252b
doc: Update docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents:
19833
diff
changeset
|
33 ## |
30568
82b685157e2b
doc: Update documentation in audio/ directory.
Rik <rik@octave.org>
parents:
30564
diff
changeset
|
34 ## The audio signal @var{y} can be a vector or a two-column array representing |
20158
7503499a252b
doc: Update docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents:
19833
diff
changeset
|
35 ## mono or stereo audio, respectively. |
7503499a252b
doc: Update docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents:
19833
diff
changeset
|
36 ## |
7503499a252b
doc: Update docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents:
19833
diff
changeset
|
37 ## If @var{fs} is not given, a default sample rate of 8000 samples per second |
7503499a252b
doc: Update docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents:
19833
diff
changeset
|
38 ## is used. |
7503499a252b
doc: Update docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents:
19833
diff
changeset
|
39 ## |
7503499a252b
doc: Update docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents:
19833
diff
changeset
|
40 ## The optional argument @var{nbits} specifies the bit depth to play to the |
7503499a252b
doc: Update docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents:
19833
diff
changeset
|
41 ## audio device and defaults to 8 bits. |
19682
c2478360291f
New functions sound and soundsc
Mike Miller <mtmiller@ieee.org>
parents:
diff
changeset
|
42 ## |
21546
f7f97d7e9294
doc: Wrap m-file docstrings to 79 characters + newline (80 total).
Rik <rik@octave.org>
parents:
20852
diff
changeset
|
43 ## By default, @var{y} is automatically normalized to the range [-1, 1]. If |
f7f97d7e9294
doc: Wrap m-file docstrings to 79 characters + newline (80 total).
Rik <rik@octave.org>
parents:
20852
diff
changeset
|
44 ## the range [@var{ymin}, @var{ymax}] is given, then elements of @var{y} |
f7f97d7e9294
doc: Wrap m-file docstrings to 79 characters + newline (80 total).
Rik <rik@octave.org>
parents:
20852
diff
changeset
|
45 ## that fall within the range @var{ymin} @leq{} @var{y} @leq{} @var{ymax} |
f7f97d7e9294
doc: Wrap m-file docstrings to 79 characters + newline (80 total).
Rik <rik@octave.org>
parents:
20852
diff
changeset
|
46 ## are scaled to the range [-1, 1] instead. |
19682
c2478360291f
New functions sound and soundsc
Mike Miller <mtmiller@ieee.org>
parents:
diff
changeset
|
47 ## |
c2478360291f
New functions sound and soundsc
Mike Miller <mtmiller@ieee.org>
parents:
diff
changeset
|
48 ## For more control over audio playback, use the @code{audioplayer} class. |
30568
82b685157e2b
doc: Update documentation in audio/ directory.
Rik <rik@octave.org>
parents:
30564
diff
changeset
|
49 ## @seealso{sound, @audioplayer/audioplayer, record} |
19682
c2478360291f
New functions sound and soundsc
Mike Miller <mtmiller@ieee.org>
parents:
diff
changeset
|
50 ## @end deftypefn |
c2478360291f
New functions sound and soundsc
Mike Miller <mtmiller@ieee.org>
parents:
diff
changeset
|
51 |
c2478360291f
New functions sound and soundsc
Mike Miller <mtmiller@ieee.org>
parents:
diff
changeset
|
52 function soundsc (y, fs, nbits, yrange) |
c2478360291f
New functions sound and soundsc
Mike Miller <mtmiller@ieee.org>
parents:
diff
changeset
|
53 |
28789
28de41192f3c
Eliminate unneeded verification of nargin, nargout in m-files.
Rik <rik@octave.org>
parents:
27923
diff
changeset
|
54 if (nargin < 1) |
19682
c2478360291f
New functions sound and soundsc
Mike Miller <mtmiller@ieee.org>
parents:
diff
changeset
|
55 print_usage (); |
c2478360291f
New functions sound and soundsc
Mike Miller <mtmiller@ieee.org>
parents:
diff
changeset
|
56 endif |
c2478360291f
New functions sound and soundsc
Mike Miller <mtmiller@ieee.org>
parents:
diff
changeset
|
57 |
c2478360291f
New functions sound and soundsc
Mike Miller <mtmiller@ieee.org>
parents:
diff
changeset
|
58 if (nargin < 4) |
c2478360291f
New functions sound and soundsc
Mike Miller <mtmiller@ieee.org>
parents:
diff
changeset
|
59 yrange = []; |
c2478360291f
New functions sound and soundsc
Mike Miller <mtmiller@ieee.org>
parents:
diff
changeset
|
60 endif |
c2478360291f
New functions sound and soundsc
Mike Miller <mtmiller@ieee.org>
parents:
diff
changeset
|
61 |
c2478360291f
New functions sound and soundsc
Mike Miller <mtmiller@ieee.org>
parents:
diff
changeset
|
62 if (nargin < 2 || isempty (fs)) |
c2478360291f
New functions sound and soundsc
Mike Miller <mtmiller@ieee.org>
parents:
diff
changeset
|
63 fs = 8000; |
19833
9fc020886ae9
maint: Clean up m-files to follow Octave coding conventions.
Rik <rik@octave.org>
parents:
19795
diff
changeset
|
64 elseif (nargin == 2 && numel (fs) > 1) |
19682
c2478360291f
New functions sound and soundsc
Mike Miller <mtmiller@ieee.org>
parents:
diff
changeset
|
65 yrange = fs; |
c2478360291f
New functions sound and soundsc
Mike Miller <mtmiller@ieee.org>
parents:
diff
changeset
|
66 fs = 8000; |
28886
d8318c12d903
test: remove unnecessary BIST tests in m-files checking for excessive number of inputs.
Rik <rik@octave.org>
parents:
28789
diff
changeset
|
67 elseif (! (isscalar (fs) && fs > 0)) |
19682
c2478360291f
New functions sound and soundsc
Mike Miller <mtmiller@ieee.org>
parents:
diff
changeset
|
68 error ("soundsc: sample rate FS must be a positive number"); |
c2478360291f
New functions sound and soundsc
Mike Miller <mtmiller@ieee.org>
parents:
diff
changeset
|
69 endif |
c2478360291f
New functions sound and soundsc
Mike Miller <mtmiller@ieee.org>
parents:
diff
changeset
|
70 |
c2478360291f
New functions sound and soundsc
Mike Miller <mtmiller@ieee.org>
parents:
diff
changeset
|
71 if (nargin < 3 || isempty (nbits)) |
c2478360291f
New functions sound and soundsc
Mike Miller <mtmiller@ieee.org>
parents:
diff
changeset
|
72 nbits = 8; |
19833
9fc020886ae9
maint: Clean up m-files to follow Octave coding conventions.
Rik <rik@octave.org>
parents:
19795
diff
changeset
|
73 elseif (nargin == 3 && numel (nbits) > 1) |
19682
c2478360291f
New functions sound and soundsc
Mike Miller <mtmiller@ieee.org>
parents:
diff
changeset
|
74 yrange = nbits; |
c2478360291f
New functions sound and soundsc
Mike Miller <mtmiller@ieee.org>
parents:
diff
changeset
|
75 nbits = 8; |
c2478360291f
New functions sound and soundsc
Mike Miller <mtmiller@ieee.org>
parents:
diff
changeset
|
76 elseif (! (isscalar (nbits) && (nbits == 8 || nbits == 16 || nbits == 24))) |
c2478360291f
New functions sound and soundsc
Mike Miller <mtmiller@ieee.org>
parents:
diff
changeset
|
77 error ("soundsc: bit depth NBITS must be 8, 16, or 24"); |
c2478360291f
New functions sound and soundsc
Mike Miller <mtmiller@ieee.org>
parents:
diff
changeset
|
78 endif |
c2478360291f
New functions sound and soundsc
Mike Miller <mtmiller@ieee.org>
parents:
diff
changeset
|
79 |
c2478360291f
New functions sound and soundsc
Mike Miller <mtmiller@ieee.org>
parents:
diff
changeset
|
80 if (isreal (yrange) && (numel (yrange) == 2) && (yrange(1) <= yrange(2))) |
c2478360291f
New functions sound and soundsc
Mike Miller <mtmiller@ieee.org>
parents:
diff
changeset
|
81 ymin = yrange(1); |
c2478360291f
New functions sound and soundsc
Mike Miller <mtmiller@ieee.org>
parents:
diff
changeset
|
82 ymax = yrange(2); |
c2478360291f
New functions sound and soundsc
Mike Miller <mtmiller@ieee.org>
parents:
diff
changeset
|
83 elseif (isempty (yrange)) |
c2478360291f
New functions sound and soundsc
Mike Miller <mtmiller@ieee.org>
parents:
diff
changeset
|
84 ymin = min (y(:)); |
c2478360291f
New functions sound and soundsc
Mike Miller <mtmiller@ieee.org>
parents:
diff
changeset
|
85 ymax = max (y(:)); |
c2478360291f
New functions sound and soundsc
Mike Miller <mtmiller@ieee.org>
parents:
diff
changeset
|
86 else |
c2478360291f
New functions sound and soundsc
Mike Miller <mtmiller@ieee.org>
parents:
diff
changeset
|
87 error ("soundsc: audio range must be a 2-element [YMIN, YMAX] vector"); |
c2478360291f
New functions sound and soundsc
Mike Miller <mtmiller@ieee.org>
parents:
diff
changeset
|
88 endif |
c2478360291f
New functions sound and soundsc
Mike Miller <mtmiller@ieee.org>
parents:
diff
changeset
|
89 |
c2478360291f
New functions sound and soundsc
Mike Miller <mtmiller@ieee.org>
parents:
diff
changeset
|
90 ymin = double (ymin); |
c2478360291f
New functions sound and soundsc
Mike Miller <mtmiller@ieee.org>
parents:
diff
changeset
|
91 ymax = double (ymax); |
c2478360291f
New functions sound and soundsc
Mike Miller <mtmiller@ieee.org>
parents:
diff
changeset
|
92 ymedian = (ymax + ymin) / 2; |
c2478360291f
New functions sound and soundsc
Mike Miller <mtmiller@ieee.org>
parents:
diff
changeset
|
93 yscale = 2 / (ymax - ymin); |
c2478360291f
New functions sound and soundsc
Mike Miller <mtmiller@ieee.org>
parents:
diff
changeset
|
94 |
c2478360291f
New functions sound and soundsc
Mike Miller <mtmiller@ieee.org>
parents:
diff
changeset
|
95 y = (double (y) - ymedian) .* yscale; |
c2478360291f
New functions sound and soundsc
Mike Miller <mtmiller@ieee.org>
parents:
diff
changeset
|
96 |
c2478360291f
New functions sound and soundsc
Mike Miller <mtmiller@ieee.org>
parents:
diff
changeset
|
97 play = audioplayer (y, fs, nbits); |
c2478360291f
New functions sound and soundsc
Mike Miller <mtmiller@ieee.org>
parents:
diff
changeset
|
98 |
c2478360291f
New functions sound and soundsc
Mike Miller <mtmiller@ieee.org>
parents:
diff
changeset
|
99 playblocking (play); |
c2478360291f
New functions sound and soundsc
Mike Miller <mtmiller@ieee.org>
parents:
diff
changeset
|
100 |
c2478360291f
New functions sound and soundsc
Mike Miller <mtmiller@ieee.org>
parents:
diff
changeset
|
101 endfunction |
c2478360291f
New functions sound and soundsc
Mike Miller <mtmiller@ieee.org>
parents:
diff
changeset
|
102 |
c2478360291f
New functions sound and soundsc
Mike Miller <mtmiller@ieee.org>
parents:
diff
changeset
|
103 |
c2478360291f
New functions sound and soundsc
Mike Miller <mtmiller@ieee.org>
parents:
diff
changeset
|
104 ## Tests of soundsc must not actually play anything. |
19833
9fc020886ae9
maint: Clean up m-files to follow Octave coding conventions.
Rik <rik@octave.org>
parents:
19795
diff
changeset
|
105 ## Test input validation |
28886
d8318c12d903
test: remove unnecessary BIST tests in m-files checking for excessive number of inputs.
Rik <rik@octave.org>
parents:
28789
diff
changeset
|
106 %!error <Invalid call> soundsc () |
d8318c12d903
test: remove unnecessary BIST tests in m-files checking for excessive number of inputs.
Rik <rik@octave.org>
parents:
28789
diff
changeset
|
107 %!error <FS must be a positive number> soundsc (1, ones (2,2), 8) |
d8318c12d903
test: remove unnecessary BIST tests in m-files checking for excessive number of inputs.
Rik <rik@octave.org>
parents:
28789
diff
changeset
|
108 %!error <FS must be a positive number> soundsc (1, -1) |
d8318c12d903
test: remove unnecessary BIST tests in m-files checking for excessive number of inputs.
Rik <rik@octave.org>
parents:
28789
diff
changeset
|
109 %!error <NBITS must be 8, 16, or 24> soundsc (1, [], 2) |
d8318c12d903
test: remove unnecessary BIST tests in m-files checking for excessive number of inputs.
Rik <rik@octave.org>
parents:
28789
diff
changeset
|
110 %!error <range must be a 2-element .* vector> soundsc (1, [2 1]) |
d8318c12d903
test: remove unnecessary BIST tests in m-files checking for excessive number of inputs.
Rik <rik@octave.org>
parents:
28789
diff
changeset
|
111 %!error <range must be a 2-element .* vector> soundsc (1, [1 2 3]) |
d8318c12d903
test: remove unnecessary BIST tests in m-files checking for excessive number of inputs.
Rik <rik@octave.org>
parents:
28789
diff
changeset
|
112 %!error <range must be a 2-element .* vector> soundsc (1, 8000, [2 1]) |
d8318c12d903
test: remove unnecessary BIST tests in m-files checking for excessive number of inputs.
Rik <rik@octave.org>
parents:
28789
diff
changeset
|
113 %!error <range must be a 2-element .* vector> soundsc (1, 8000, [1 2 3]) |
d8318c12d903
test: remove unnecessary BIST tests in m-files checking for excessive number of inputs.
Rik <rik@octave.org>
parents:
28789
diff
changeset
|
114 %!error <range must be a 2-element .* vector> soundsc (1, 8000, 8, [2 1]) |
d8318c12d903
test: remove unnecessary BIST tests in m-files checking for excessive number of inputs.
Rik <rik@octave.org>
parents:
28789
diff
changeset
|
115 %!error <range must be a 2-element .* vector> soundsc (1, 8000, 8, [1 2 3]) |