Project: Speex

Revision: 14935

Author: jm

Date: 21 May 2008 19:44:56

• /trunk/speex/doc/manual.lyx

  ......	@@ -4556,7 +4556,11 @@
  4556	4556	\end_layout
  4557	4557
  4558	4558	\begin_layout Itemize
  4559		When it comes to echo tail length (filter length), longer is *not* better.
  	4559	When it comes to echo tail length (filter length), longer is
  	4560	\series bold
  	4561	not
  	4562	\series default
  	4563	better.
  4560	4564	Actually, the longer the tail length, the longer it takes for the filter
  4561	4565	to adapt.
  4562	4566	Of course, a tail length that is too short will not cancel enough echo,
  ......	@@ -4964,10 +4968,56 @@
  4964	4968	\end_layout
  4965	4969
  4966	4970	\begin_layout Standard
  4967		where nb_channels is the number of channels that will be used (either interleave
  4968		d or non-interleaved), input_rate is the sampling rate of the input stream,
  4969		output_rate is the sampling rate of the output stream and quality is the
  4970		requested quality setting (0 to 10).
  	4971	where
  	4972	\begin_inset listings
  	4973	inline true
  	4974	status collapsed
  	4975
  	4976	\begin_layout Standard
  	4977
  	4978	nb_channels
  	4979	\end_layout
  	4980
  	4981	\end_inset
  	4982
  	4983	is the number of channels that will be used (either interleaved or non-interlea
  	4984	ved),
  	4985	\begin_inset listings
  	4986	inline true
  	4987	status collapsed
  	4988
  	4989	\begin_layout Standard
  	4990
  	4991	input_rate
  	4992	\end_layout
  	4993
  	4994	\end_inset
  	4995
  	4996	is the sampling rate of the input stream,
  	4997	\begin_inset listings
  	4998	inline true
  	4999	status collapsed
  	5000
  	5001	\begin_layout Standard
  	5002
  	5003	output_rate
  	5004	\end_layout
  	5005
  	5006	\end_inset
  	5007
  	5008	is the sampling rate of the output stream and
  	5009	\begin_inset listings
  	5010	inline true
  	5011	status collapsed
  	5012
  	5013	\begin_layout Standard
  	5014
  	5015	quality
  	5016	\end_layout
  	5017
  	5018	\end_inset
  	5019
  	5020	is the requested quality setting (0 to 10).
  4971	5021	The quality parameter is useful for controlling the quality/complexity/latency
  4972	5022	tradeoff.
  4973	5023	Using a higher quality setting means less noise/aliasing, a higher complexity
  ......	@@ -4995,7 +5045,19 @@
  4995	5045
  4996	5046	\end_inset
  4997	5047
  4998		where channelID is the ID of the channel to be processed.
  	5048	where
  	5049	\begin_inset listings
  	5050	inline true
  	5051	status collapsed
  	5052
  	5053	\begin_layout Standard
  	5054
  	5055	channelID
  	5056	\end_layout
  	5057
  	5058	\end_inset
  	5059
  	5060	is the ID of the channel to be processed.
  4999	5061	For a mono stream, use 0.
  5000	5062	The
  5001	5063	\emph on
  ......	@@ -5003,32 +5065,90 @@
  5003	5065	\emph default
  5004	5066	pointer points to the first sample of the input buffer for the selected
  5005	5067	channel and
  5006		\emph on
  	5068	\begin_inset listings
  	5069	inline true
  	5070	status collapsed
  	5071
  	5072	\begin_layout Standard
  	5073
  5007	5074	out
  5008		\emph default
  	5075	\end_layout
  	5076
  	5077	\end_inset
  	5078
  5009	5079	points to the first sample of the output.
  5010	5080	The size of the input and output buffers are specified by
  5011		\emph on
  	5081	\begin_inset listings
  	5082	inline true
  	5083	status collapsed
  	5084
  	5085	\begin_layout Standard
  	5086
  5012	5087	in_length
  5013		\emph default
  	5088	\end_layout
  	5089
  	5090	\end_inset
  	5091
  5014	5092	and
  5015		\emph on
  	5093	\begin_inset listings
  	5094	inline true
  	5095	status collapsed
  	5096
  	5097	\begin_layout Standard
  	5098
  5016	5099	out_length
  5017		\emph default
  	5100	\end_layout
  	5101
  	5102	\end_inset
  	5103
  5018	5104	respectively.
  5019	5105	Upon completion, these values are replaced by the number of samples read
  5020	5106	and written by the resampler.
  5021	5107	Unless an error occurs, either all input samples will be read or all output
  5022	5108	samples will be written to (or both).
  5023		For floating-point samples, the function speex_resampler_process_float()
  	5109	For floating-point samples, the function
  	5110	\begin_inset listings
  	5111	inline true
  	5112	status open
  	5113
  	5114	\begin_layout Standard
  	5115
  	5116	speex_resampler_process_float()
  	5117	\end_layout
  	5118
  	5119	\end_inset
  	5120
  5024	5121	behaves similarly.
  5025	5122	\end_layout
  5026	5123
  5027	5124	\begin_layout Standard
  5028	5125	It is also possible to process multiple channels at once.
  5029		To do that, you can use speex_resampler_process_interleaved_int() or speex_resa
  5030		mpler_process_interleaved_float().
  5031		The arguments are the same except that there is no channelID argument.
  	5126	To do that, you can use speex_resampler_process_interleaved_int() or
  	5127	\begin_inset listings
  	5128	inline true
  	5129	status open
  	5130
  	5131	\begin_layout Standard
  	5132
  	5133	speex_resampler_process_interleaved_float()
  	5134	\end_layout
  	5135
  	5136	\end_inset
  	5137
  	5138	.
  	5139	The arguments are the same except that there is no
  	5140	\begin_inset listings
  	5141	inline true
  	5142	status collapsed
  	5143
  	5144	\begin_layout Standard
  	5145
  	5146	channelID
  	5147	\end_layout
  	5148
  	5149	\end_inset
  	5150
  	5151	argument.
  5032	5152	Note that the
  5033	5153	\series bold
  5034	5154	length parameters are per-channel
  ......	@@ -5041,8 +5161,31 @@
  5041	5161	\begin_layout Standard
  5042	5162	The resampler allows changing the quality and input/output sampling frequencies
  5043	5163	on the fly without glitches.
  5044		This can be done with calls such as speex_resampler_set_quality() and speex_res
  5045		ampler_set_rate().
  	5164	This can be done with calls such as
  	5165	\begin_inset listings
  	5166	inline true
  	5167	status open
  	5168
  	5169	\begin_layout Standard
  	5170
  	5171	speex_resampler_set_quality()
  	5172	\end_layout
  	5173
  	5174	\end_inset
  	5175
  	5176	and
  	5177	\begin_inset listings
  	5178	inline true
  	5179	status open
  	5180
  	5181	\begin_layout Standard
  	5182
  	5183	speex_resampler_set_rate()
  	5184	\end_layout
  	5185
  	5186	\end_inset
  	5187
  	5188	.
  5046	5189	The only side effect is that a new filter will have to be recomputed, consuming
  5047	5190	many CPU cycles.
  5048	5191
  ......	@@ -5051,7 +5194,19 @@
  5051	5194	\begin_layout Standard
  5052	5195	When resampling a file, it is often desirable to have the output file perfectly
  5053	5196	synchronised with the input.
  5054		To do that, you need to call speex_resampler_skip_zeros()
  	5197	To do that, you need to call
  	5198	\begin_inset listings
  	5199	inline true
  	5200	status open
  	5201
  	5202	\begin_layout Standard
  	5203
  	5204	speex_resampler_skip_zeros()
  	5205	\end_layout
  	5206
  	5207	\end_inset
  	5208
  	5209
  5055	5210	\series bold
  5056	5211	before
  5057	5212	\series default
  ......	@@ -5059,7 +5214,19 @@
  5059	5214	For real-time applications (e.g.
  5060	5215	VoIP), it is not recommended to do that as the first process frame will
  5061	5216	be shorter to compensate for the delay (the skipped zeros).
  5062		To destroy a resampler state, just call speex_resampler_destroy().
  	5217	To destroy a resampler state, just call
  	5218	\begin_inset listings
  	5219	inline true
  	5220	status open
  	5221
  	5222	\begin_layout Standard
  	5223
  	5224	speex_resampler_destroy()
  	5225	\end_layout
  	5226
  	5227	\end_inset
  	5228
  	5229	.
  5063	5230	\end_layout
  5064	5231
  5065	5232	\begin_layout Section