Mercurial > octave

comparison scripts/audio/@audioplayer/audioplayer.m @ 30568:82b685157e2b

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
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 6d96538052b9
comparison
equal deleted inserted replaced
30567:3eeaba530a03 30568:82b685157e2b
30 ## @deftypefnx {} {@var{player} =} audioplayer (@var{recorder}) 30 ## @deftypefnx {} {@var{player} =} audioplayer (@var{recorder})
31 ## @deftypefnx {} {@var{player} =} audioplayer (@var{recorder}, @var{id}) 31 ## @deftypefnx {} {@var{player} =} audioplayer (@var{recorder}, @var{id})
32 ## Create an audioplayer object that will play back data @var{y} at sample 32 ## Create an audioplayer object that will play back data @var{y} at sample
33 ## rate @var{fs}. 33 ## rate @var{fs}.
34 ## 34 ##
35 ## The optional arguments @var{nbits}, and @var{id} specify the bit depth and 35 ## The signal @var{y} can be a vector (mono audio) or a two-dimensional array
36 ## player device id, respectively. Device IDs may be found using the 36 ## (multi-channel audio).
37 ## audiodevinfo function. Given an audioplayer object, use the data from the 37 ##
38 ## object to initialize the player. 38 ## The optional arguments @var{nbits} and @var{id} specify the number of bits
39 ## 39 ## per sample and player device ID, respectively. Device IDs may be found
40 ## The signal @var{y} can be a vector or a two-dimensional array. 40 ## using the @code{audiodevinfo} function.
41 ## 41 ##
42 ## The following example will create an audioplayer object that will play 42 ## Given an audiorecorder object @var{recorder}, use the data from the object
43 ## back one second of white noise at 44100 sample rate using 8 bits per 43 ## to initialize the player.
44 ## sample. 44 ##
45 ## The list of actions for an audioplayer object are shown below. All
46 ## methods require an audioplayer object as the first argument.
47 ##
48 ## @multitable @columnfractions 0.2 0.75
49 ## @headitem Method @tab Description
50 ## @item get @tab Read audioplayer property values
51 ## @item isplaying @tab Return true if audioplayer is playing
52 ## @item pause @tab Pause audioplayer playback
53 ## @item play @tab Play audio stored in audioplayer object w/o blocking
54 ## @item playblocking @tab Play audio stored in audioplayer object
55 ## @item resume @tab Resume playback after pause
56 ## @item set @tab Write audioplayer property values
57 ## @item stop @tab Stop playback
58 ## @end multitable
59 ##
60 ## Example
61 ##
62 ## Create an audioplayer object that will play back one second of white noise
63 ## at 44100 sample rate using 8 bits per sample.
45 ## 64 ##
46 ## @example 65 ## @example
47 ## @group 66 ## @group
48 ## y = 0.25 * randn (2, 44100); 67 ## y = 0.25 * randn (2, 44100);
49 ## player = audioplayer (y, 44100, 8); 68 ## player = audioplayer (y, 44100, 8);
50 ## play (player); 69 ## play (player);
51 ## @end group 70 ## @end group
52 ## @end example 71 ## @end example
72 ## @seealso{@audioplayer/get, @audioplayer/isplaying, @audioplayer/pause,
73 ## @audioplayer/play, @audioplayer/playblocking, @audioplayer/resume,
74 ## @audioplayer/set, @audioplayer/stop, audiodevinfo,
75 ## @audiorecorder/audiorecorder, sound, soundsc}
53 ## @end deftypefn 76 ## @end deftypefn
54 77
78 ################################################################################
55 ## FIXME: callbacks don't work properly, apparently because portaudio 79 ## FIXME: callbacks don't work properly, apparently because portaudio
56 ## will execute the callbacks in a separate thread, and calling Octave 80 ## will execute the callbacks in a separate thread, and calling Octave
57 ## functions in a separate thread which is likely to cause trouble with 81 ## functions in a separate thread which is likely to cause trouble with
58 ## all of Octave's global data... 82 ## all of Octave's global data...
59 ## 83 ##
83 ## player = audioplayer (@@callback_sine, 44100); 107 ## player = audioplayer (@@callback_sine, 44100);
84 ## play (player); 108 ## play (player);
85 ## # play for as long as you want 109 ## # play for as long as you want
86 ## stop (player); 110 ## stop (player);
87 ## @end group 111 ## @end group
112 ################################################################################
88 113
89 function player = audioplayer (varargin) 114 function player = audioplayer (varargin)
90 115
91 if (nargin < 1 || nargin > 4 116 if (nargin < 1 || nargin > 4
92 || (nargin < 2 && ! (is_function_handle (varargin{1}) 117 || (nargin < 2 && ! (is_function_handle (varargin{1})