spandsp  0.0.6
time_scale.h
1 /*
2  * SpanDSP - a series of DSP components for telephony
3  *
4  * time_scale.h - Time scaling for linear speech data
5  *
6  * Written by Steve Underwood <steveu@coppice.org>
7  *
8  * Copyright (C) 2004 Steve Underwood
9  *
10  * All rights reserved.
11  *
12  * This program is free software; you can redistribute it and/or modify
13  * it under the terms of the GNU Lesser General Public License version 2.1,
14  * as published by the Free Software Foundation.
15  *
16  * This program is distributed in the hope that it will be useful,
17  * but WITHOUT ANY WARRANTY; without even the implied warranty of
18  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19  * GNU Lesser General Public License for more details.
20  *
21  * You should have received a copy of the GNU Lesser General Public
22  * License along with this program; if not, write to the Free Software
23  * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
24  */
25 
26 #if !defined(_SPANDSP_TIME_SCALE_H_)
27 #define _SPANDSP_TIME_SCALE_H_
28 
29 /*! \page time_scale_page Time scaling speech
30 \section time_scale_page_sec_1 What does it do?
31 The time scaling module allows speech files to be played back at a
32 different speed from the speed at which they were recorded. If this
33 were done by simply speeding up or slowing down replay, the pitch of
34 the voice would change, and sound very odd. This module keeps the pitch
35 of the voice at its original level.
36 
37 The speed of the voice may be altered over a wide range. However, the practical
38 useful rates are between about half normal speed and twice normal speed.
39 
40 \section time_scale_page_sec_2 How does it work?
41 The time scaling module is based on the Pointer Interval Controlled
42 OverLap and Add (PICOLA) method, developed by Morita Naotaka.
43 Mikio Ikeda has an excellent web page on this subject at
44 http://keizai.yokkaichi-u.ac.jp/~ikeda/research/picola.html
45 There is also working code there. This implementation uses
46 exactly the same algorithms, but the code is a complete rewrite.
47 Mikio's code batch processes files. This version works incrementally
48 on streams, and allows multiple streams to be processed concurrently.
49 
50 \section time_scale_page_sec_3 How do I used it?
51 The output buffer must be big enough to hold the maximum number of samples which
52 could result from the data in the input buffer, which is:
53 
54  input_len*playout_rate + sample_rate/TIME_SCALE_MIN_PITCH + 1
55 */
56 
57 /*! Audio time scaling descriptor. */
59 
60 #if defined(__cplusplus)
61 extern "C"
62 {
63 #endif
64 
65 /*! Initialise a time scale context. This must be called before the first
66  use of the context, to initialise its contents.
67  \brief Initialise a time scale context.
68  \param s The time scale context.
69  \param sample_rate The sample rate of the signal.
70  \param playout_rate The ratio between the output speed and the input speed.
71  \return A pointer to the context, or NULL if there was a problem. */
72 SPAN_DECLARE(time_scale_state_t *) time_scale_init(time_scale_state_t *s, int sample_rate, float playout_rate);
73 
74 /*! \brief Release a time scale context.
75  \param s The time scale context.
76  \return 0 for OK, else -1. */
77 SPAN_DECLARE(int) time_scale_release(time_scale_state_t *s);
78 
79 /*! \brief Free a time scale context.
80  \param s The time scale context.
81  \return 0 for OK, else -1. */
82 SPAN_DECLARE(int) time_scale_free(time_scale_state_t *s);
83 
84 /*! Change the time scale rate.
85  \brief Change the time scale rate.
86  \param s The time scale context.
87  \param playout_rate The ratio between the output speed and the input speed.
88  \return 0 if changed OK, else -1. */
89 SPAN_DECLARE(int) time_scale_rate(time_scale_state_t *s, float playout_rate);
90 
91 /*! Find the maximum possible samples which could result from scaling the specified
92  number of input samples, at the current playback rate.
93  \brief Find the maximum possible output samples.
94  \param s The time scale context.
95  \param input_len The number of input samples.
96  \return The maximum possible output samples. */
97 SPAN_DECLARE(int) time_scale_max_output_len(time_scale_state_t *s, int input_len);
98 
99 /*! Time scale a chunk of audio samples.
100  \brief Time scale a chunk of audio samples.
101  \param s The time scale context.
102  \param out The output audio sample buffer. This must be large enough to accept
103  the longest possible result from processing the input data. See the
104  algorithm documentation for how the longest possible result may be calculated.
105  \param in The input audio sample buffer.
106  \param len The number of input samples.
107  \return The number of output samples.
108 */
109 SPAN_DECLARE(int) time_scale(time_scale_state_t *s, int16_t out[], int16_t in[], int len);
110 
111 #if defined(__cplusplus)
112 }
113 #endif
114 
115 #endif
116 /*- End of file ------------------------------------------------------------*/
int time_scale_rate(time_scale_state_t *s, float playout_rate)
Change the time scale rate.
Definition: time_scale.c:101
int time_scale(time_scale_state_t *s, int16_t out[], int16_t in[], int len)
Time scale a chunk of audio samples.
Definition: time_scale.c:172
int time_scale_release(time_scale_state_t *s)
Release a time scale context.
Definition: time_scale.c:159
int time_scale_free(time_scale_state_t *s)
Free a time scale context.
Definition: time_scale.c:165
int time_scale_max_output_len(time_scale_state_t *s, int input_len)
Find the maximum possible output samples.
Definition: time_scale.c:280
Definition: private/time_scale.h:35
time_scale_state_t * time_scale_init(time_scale_state_t *s, int sample_rate, float playout_rate)
Initialise a time scale context.
Definition: time_scale.c:126