changeset 19844:0165d9607624

Deprecate audio functions loadaudio, playaudio, saveaudio, and setaudio. * NEWS: Announce deprecation. * scripts/deprecated/loadaudio.m, scripts/deprecated/playaudio.m, scripts/deprecated/saveaudio.m, scripts/deprecated/setaudio.m: Move from scripts/audio. Add deprecation warnings to code and to docstrings. * audio.txi: Remove from manual. * lin2mu.m, mu2lin.m, record.m: Remove seealso links. * scripts/deprecated/module.mk: Add to build system in deprecated directory. * scripts/audio/module.mk: Remove from build system in audio directory.
author Mike Miller <mtmiller@ieee.org>
date Sat, 31 Jan 2015 10:23:52 -0500
parents 408361a8c72f
children 16f21db320b5
files NEWS doc/interpreter/audio.txi scripts/audio/lin2mu.m scripts/audio/loadaudio.m scripts/audio/module.mk scripts/audio/mu2lin.m scripts/audio/playaudio.m scripts/audio/record.m scripts/audio/saveaudio.m scripts/audio/setaudio.m scripts/deprecated/loadaudio.m scripts/deprecated/module.mk scripts/deprecated/playaudio.m scripts/deprecated/saveaudio.m scripts/deprecated/setaudio.m
diffstat 11 files changed, 56 insertions(+), 23 deletions(-) [+]
line wrap: on
line diff
--- a/NEWS
+++ b/NEWS
@@ -195,14 +195,18 @@
       finite               | isfinite
       fmod                 | rem
       fnmatch              | glob or regexp
+      loadaudio            | audioread
       luinc                | ilu or ichol
       nfields              | numfields
       octave_tmp_file_name | tempname
+      playaudio            | audioplayer
+      saveaudio            | audiowrite
       syl                  | sylvester
       usage                | print_usage
 
       allow_noninteger_range_as_index
       do_braindead_shortcircuit_evaluation
+      setaudio
 
  ** The following functions were deprecated in Octave 3.8 and will be
     removed from Octave 4.2 (or whatever version is the second major
--- a/doc/interpreter/audio.txi
+++ b/doc/interpreter/audio.txi
@@ -176,24 +176,8 @@
 
 @DOCSTRING(mu2lin)
 
-@DOCSTRING(loadaudio)
-
-@DOCSTRING(saveaudio)
-
-The following functions for audio I/O require special A/D hardware and
-operating system support.  It is assumed that audio data in linear
-encoding can be played and recorded by reading from and writing to
-@file{/dev/dsp}, and that similarly @file{/dev/audio} is used for mu-law
-encoding.  These file names are system-dependent.  Improvements so that
-these functions will work without modification on a wide variety of
-hardware are welcome.
-
-@DOCSTRING(playaudio)
-
 @DOCSTRING(record)
 
-@DOCSTRING(setaudio)
-
 @DOCSTRING(wavread)
 
 @DOCSTRING(wavwrite)
--- a/scripts/audio/lin2mu.m
+++ b/scripts/audio/lin2mu.m
@@ -25,7 +25,7 @@
 ##
 ## If @var{n} is not specified it defaults to 0, 8, or 16 depending on
 ## the range of values in @var{x}.
-## @seealso{mu2lin, loadaudio, saveaudio}
+## @seealso{mu2lin}
 ## @end deftypefn
 
 
--- a/scripts/audio/module.mk
+++ b/scripts/audio/module.mk
@@ -2,12 +2,8 @@
 
 audio_FCN_FILES = \
   audio/lin2mu.m \
-  audio/loadaudio.m \
   audio/mu2lin.m \
-  audio/playaudio.m \
   audio/record.m \
-  audio/saveaudio.m \
-  audio/setaudio.m \
   audio/wavread.m \
   audio/wavwrite.m \
   audio/@audioplayer/__get_properties__.m \
--- a/scripts/audio/mu2lin.m
+++ b/scripts/audio/mu2lin.m
@@ -24,7 +24,7 @@
 ## is 0.
 ##
 ## If @var{n} is not specified it defaults to 0.
-## @seealso{lin2mu, loadaudio, saveaudio}
+## @seealso{lin2mu}
 ## @end deftypefn
 
 ## Author:  Andreas Weingessel <Andreas.Weingessel@ci.tuwien.ac.at>
--- a/scripts/audio/record.m
+++ b/scripts/audio/record.m
@@ -22,7 +22,7 @@
 ## default value for @var{sampling_rate} is 8000 samples per second, or
 ## 8kHz.  The program waits until the user types @key{RET} and then
 ## immediately starts to record.
-## @seealso{lin2mu, mu2lin, loadaudio, saveaudio, playaudio, setaudio}
+## @seealso{lin2mu, mu2lin}
 ## @end deftypefn
 
 ## Author: AW <Andreas.Weingessel@ci.tuwien.ac.at>
rename from scripts/audio/loadaudio.m
rename to scripts/deprecated/loadaudio.m
--- a/scripts/audio/loadaudio.m
+++ b/scripts/deprecated/loadaudio.m
@@ -18,6 +18,10 @@
 
 ## -*- texinfo -*-
 ## @deftypefn {Function File} {} loadaudio (@var{name}, @var{ext}, @var{bps})
+##
+## @code{loadaudio} is deprecated and will be removed in Octave version 4.4.
+## Please use @code{audioread} in all new code.
+##
 ## Load audio data from the file @file{@var{name}.@var{ext}} into the
 ## vector @var{x}.
 ##
@@ -38,6 +42,13 @@
 
 function X = loadaudio (name, ext, bps)
 
+  persistent warned = false;
+  if (! warned)
+    warned = true;
+    warning ("Octave:deprecated-function",
+             "loadaudio is obsolete and will be removed from a future version of Octave, please use audioread instead");
+  endif
+
   if (nargin == 0 || nargin > 3)
     print_usage ();
   endif
--- a/scripts/deprecated/module.mk
+++ b/scripts/deprecated/module.mk
@@ -20,12 +20,16 @@
   deprecated/java_unsigned_conversion.m \
   deprecated/javafields.m \
   deprecated/javamethods.m \
+  deprecated/loadaudio.m \
   deprecated/luinc.m \
   deprecated/nfields.m \
   deprecated/octave_tmp_file_name.m \
+  deprecated/playaudio.m \
   deprecated/re_read_readline_init_file.m \
   deprecated/read_readline_init_file.m \
+  deprecated/saveaudio.m \
   deprecated/saving_history.m \
+  deprecated/setaudio.m \
   deprecated/strmatch.m \
   deprecated/syl.m \
   deprecated/usage.m
rename from scripts/audio/playaudio.m
rename to scripts/deprecated/playaudio.m
--- a/scripts/audio/playaudio.m
+++ b/scripts/deprecated/playaudio.m
@@ -19,6 +19,10 @@
 ## -*- texinfo -*-
 ## @deftypefn  {Function File} {} playaudio (@var{name}, @var{ext})
 ## @deftypefnx {Function File} {} playaudio (@var{x})
+##
+## @code{playaudio} is deprecated and will be removed in Octave version 4.4.
+## Please use @code{audioplayer} in all new code.
+##
 ## Play the audio file @file{@var{name}.@var{ext}} or the audio data
 ## stored in the vector @var{x}.
 ## @seealso{lin2mu, mu2lin, loadaudio, saveaudio, setaudio, record}
@@ -30,6 +34,13 @@
 
 function playaudio (name, ext)
 
+  persistent warned = false;
+  if (! warned)
+    warned = true;
+    warning ("Octave:deprecated-function",
+             "playaudio is obsolete and will be removed from a future version of Octave, please use audioplayer instead");
+  endif
+
   if (nargin < 1 || nargin > 2)
     print_usage ();
   endif
rename from scripts/audio/saveaudio.m
rename to scripts/deprecated/saveaudio.m
--- a/scripts/audio/saveaudio.m
+++ b/scripts/deprecated/saveaudio.m
@@ -18,6 +18,10 @@
 
 ## -*- texinfo -*-
 ## @deftypefn {Function File} {} saveaudio (@var{name}, @var{x}, @var{ext}, @var{bps})
+##
+## @code{saveaudio} is deprecated and will be removed in Octave version 4.4.
+## Please use @code{audiowrite} in all new code.
+##
 ## Save a vector @var{x} of audio data to the file
 ## @file{@var{name}.@var{ext}}.  The optional parameters @var{ext} and
 ## @var{bps} determine the encoding and the number of bits per sample used
@@ -32,6 +36,13 @@
 
 function saveaudio (name, x, ext, bps)
 
+  persistent warned = false;
+  if (! warned)
+    warned = true;
+    warning ("Octave:deprecated-function",
+             "saveaudio is obsolete and will be removed from a future version of Octave, please use audiowrite instead");
+  endif
+
   if (nargin < 2 || nargin > 4)
     print_usage ();
   endif
rename from scripts/audio/setaudio.m
rename to scripts/deprecated/setaudio.m
--- a/scripts/audio/setaudio.m
+++ b/scripts/deprecated/setaudio.m
@@ -20,6 +20,11 @@
 ## @deftypefn  {Function File} {} setaudio ()
 ## @deftypefnx {Function File} {} setaudio (@var{w_type})
 ## @deftypefnx {Function File} {} setaudio (@var{w_type}, @var{value})
+##
+## @code{setaudio} is deprecated and will be removed in Octave version 4.4.
+## Please scale the audio signal in all new code or use the operating system's
+## native tools to adjust audio input and output levels.
+##
 ## Execute the shell command @samp{mixer}, possibly with optional
 ## arguments @var{w_type} and @var{value}.
 ## @end deftypefn
@@ -30,6 +35,13 @@
 
 function setaudio (w_type, value)
 
+  persistent warned = false;
+  if (! warned)
+    warned = true;
+    warning ("Octave:deprecated-function",
+             "setaudio is obsolete and will be removed from a future version of Octave, please scale the audio signal instead");
+  endif
+
   if (nargin == 0)
     system ("mixer");
   elseif (nargin == 1)