annotate libtwamr/tw_amr.h @ 480:332397bc80aa

doc/AMR-library-API: document public const data items
author Mychaela Falconia <falcon@freecalypso.org>
date Sun, 19 May 2024 23:18:17 +0000
parents fa0652115168
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
252
57b4053559ff libtwamr: beginning of project
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1 /*
57b4053559ff libtwamr: beginning of project
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
2 * This header file is the external public interface to libtwamr;
57b4053559ff libtwamr: beginning of project
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
3 * it should be installed in the same system include directory
307
6b33f3ba4289 libtwamr: go for single-chunk-state approach
Mychaela Falconia <falcon@freecalypso.org>
parents: 252
diff changeset
4 * as <tw_gsmfr.h> and <gsm_efr.h> for more classic GSM codecs.
252
57b4053559ff libtwamr: beginning of project
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
5 */
57b4053559ff libtwamr: beginning of project
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
6
57b4053559ff libtwamr: beginning of project
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
7 #ifndef __THEMWI_AMR_H
57b4053559ff libtwamr: beginning of project
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
8 #define __THEMWI_AMR_H
57b4053559ff libtwamr: beginning of project
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
9
57b4053559ff libtwamr: beginning of project
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
10 #include <stdint.h>
57b4053559ff libtwamr: beginning of project
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
11
57b4053559ff libtwamr: beginning of project
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
12 /* AMR definitions that matter for the public interface */
57b4053559ff libtwamr: beginning of project
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
13
57b4053559ff libtwamr: beginning of project
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
14 #define AMR_MAX_PRM 57 /* max. num. of params */
57b4053559ff libtwamr: beginning of project
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
15 #define AMR_IETF_MAX_PL 32 /* max bytes in RFC 4867 frame */
57b4053559ff libtwamr: beginning of project
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
16 #define AMR_IETF_HDR_LEN 6 /* .amr file header bytes */
57b4053559ff libtwamr: beginning of project
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
17 #define AMR_COD_WORDS 250 /* # of words in 3GPP test seq format */
57b4053559ff libtwamr: beginning of project
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
18
57b4053559ff libtwamr: beginning of project
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
19 enum RXFrameType {
57b4053559ff libtwamr: beginning of project
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
20 RX_SPEECH_GOOD = 0,
57b4053559ff libtwamr: beginning of project
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
21 RX_SPEECH_DEGRADED,
57b4053559ff libtwamr: beginning of project
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
22 RX_ONSET,
57b4053559ff libtwamr: beginning of project
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
23 RX_SPEECH_BAD,
57b4053559ff libtwamr: beginning of project
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
24 RX_SID_FIRST,
57b4053559ff libtwamr: beginning of project
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
25 RX_SID_UPDATE,
57b4053559ff libtwamr: beginning of project
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
26 RX_SID_BAD,
57b4053559ff libtwamr: beginning of project
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
27 RX_NO_DATA,
57b4053559ff libtwamr: beginning of project
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
28 RX_N_FRAMETYPES /* number of frame types */
57b4053559ff libtwamr: beginning of project
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
29 };
57b4053559ff libtwamr: beginning of project
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
30
57b4053559ff libtwamr: beginning of project
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
31 enum TXFrameType {
57b4053559ff libtwamr: beginning of project
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
32 TX_SPEECH_GOOD = 0,
57b4053559ff libtwamr: beginning of project
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
33 TX_SID_FIRST,
57b4053559ff libtwamr: beginning of project
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
34 TX_SID_UPDATE,
57b4053559ff libtwamr: beginning of project
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
35 TX_NO_DATA,
57b4053559ff libtwamr: beginning of project
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
36 TX_SPEECH_DEGRADED,
57b4053559ff libtwamr: beginning of project
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
37 TX_SPEECH_BAD,
57b4053559ff libtwamr: beginning of project
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
38 TX_SID_BAD,
57b4053559ff libtwamr: beginning of project
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
39 TX_ONSET,
57b4053559ff libtwamr: beginning of project
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
40 TX_N_FRAMETYPES /* number of frame types */
57b4053559ff libtwamr: beginning of project
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
41 };
57b4053559ff libtwamr: beginning of project
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
42
57b4053559ff libtwamr: beginning of project
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
43 enum Mode {
57b4053559ff libtwamr: beginning of project
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
44 MR475 = 0,
421
09534cdc59ec libtwamr/tw_amr.h: rm trailing spaces from enum Mode list
Mychaela Falconia <falcon@freecalypso.org>
parents: 414
diff changeset
45 MR515,
252
57b4053559ff libtwamr: beginning of project
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
46 MR59,
57b4053559ff libtwamr: beginning of project
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
47 MR67,
57b4053559ff libtwamr: beginning of project
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
48 MR74,
57b4053559ff libtwamr: beginning of project
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
49 MR795,
57b4053559ff libtwamr: beginning of project
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
50 MR102,
421
09534cdc59ec libtwamr/tw_amr.h: rm trailing spaces from enum Mode list
Mychaela Falconia <falcon@freecalypso.org>
parents: 414
diff changeset
51 MR122,
252
57b4053559ff libtwamr: beginning of project
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
52 MRDTX
57b4053559ff libtwamr: beginning of project
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
53 };
57b4053559ff libtwamr: beginning of project
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
54
57b4053559ff libtwamr: beginning of project
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
55 #define AMR_FT_NODATA 15
57b4053559ff libtwamr: beginning of project
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
56
57b4053559ff libtwamr: beginning of project
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
57 /* libtwamr encoder and decoder state */
57b4053559ff libtwamr: beginning of project
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
58
57b4053559ff libtwamr: beginning of project
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
59 struct amr_encoder_state; /* opaque to external users */
57b4053559ff libtwamr: beginning of project
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
60 struct amr_decoder_state; /* ditto */
57b4053559ff libtwamr: beginning of project
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
61
414
028ed5114e52 libtwamr: implement run-time VAD selection scheme
Mychaela Falconia <falcon@freecalypso.org>
parents: 354
diff changeset
62 struct amr_encoder_state *amr_encoder_create(int dtx, int use_vad2);
252
57b4053559ff libtwamr: beginning of project
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
63 struct amr_decoder_state *amr_decoder_create(void);
57b4053559ff libtwamr: beginning of project
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
64
57b4053559ff libtwamr: beginning of project
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
65 /* reset state to initial */
414
028ed5114e52 libtwamr: implement run-time VAD selection scheme
Mychaela Falconia <falcon@freecalypso.org>
parents: 354
diff changeset
66 void amr_encoder_reset(struct amr_encoder_state *st, int dtx, int use_vad2);
252
57b4053559ff libtwamr: beginning of project
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
67 void amr_decoder_reset(struct amr_decoder_state *st);
57b4053559ff libtwamr: beginning of project
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
68
57b4053559ff libtwamr: beginning of project
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
69 /* interface structure for passing frames of codec parameters */
57b4053559ff libtwamr: beginning of project
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
70
57b4053559ff libtwamr: beginning of project
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
71 struct amr_param_frame {
57b4053559ff libtwamr: beginning of project
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
72 uint8_t type;
57b4053559ff libtwamr: beginning of project
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
73 uint8_t mode;
57b4053559ff libtwamr: beginning of project
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
74 int16_t param[AMR_MAX_PRM];
57b4053559ff libtwamr: beginning of project
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
75 };
57b4053559ff libtwamr: beginning of project
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
76
57b4053559ff libtwamr: beginning of project
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
77 /* encoder and decoder main functions */
57b4053559ff libtwamr: beginning of project
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
78
307
6b33f3ba4289 libtwamr: go for single-chunk-state approach
Mychaela Falconia <falcon@freecalypso.org>
parents: 252
diff changeset
79 void amr_encode_frame(struct amr_encoder_state *st, enum Mode mode,
6b33f3ba4289 libtwamr: go for single-chunk-state approach
Mychaela Falconia <falcon@freecalypso.org>
parents: 252
diff changeset
80 const int16_t *pcm, struct amr_param_frame *frame);
252
57b4053559ff libtwamr: beginning of project
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
81
57b4053559ff libtwamr: beginning of project
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
82 void amr_decode_frame(struct amr_decoder_state *st,
57b4053559ff libtwamr: beginning of project
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
83 const struct amr_param_frame *frame, int16_t *pcm);
57b4053559ff libtwamr: beginning of project
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
84
57b4053559ff libtwamr: beginning of project
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
85 /* stateless utility functions: format conversions */
57b4053559ff libtwamr: beginning of project
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
86
428
ffd87f972f86 libtwamr: implement TXFrameType to RXFrameType conversion
Mychaela Falconia <falcon@freecalypso.org>
parents: 421
diff changeset
87 int amr_txtype_to_rxtype(enum TXFrameType tx_type, enum RXFrameType *rx_type);
252
57b4053559ff libtwamr: beginning of project
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
88
57b4053559ff libtwamr: beginning of project
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
89 unsigned amr_frame_to_ietf(const struct amr_param_frame *frame, uint8_t *bytes);
57b4053559ff libtwamr: beginning of project
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
90 int amr_frame_from_ietf(const uint8_t *bytes, struct amr_param_frame *frame);
57b4053559ff libtwamr: beginning of project
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
91 int amr_ietf_grok_first_octet(uint8_t fo);
57b4053559ff libtwamr: beginning of project
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
92
57b4053559ff libtwamr: beginning of project
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
93 void amr_frame_to_tseq(const struct amr_param_frame *frame, uint16_t *cod);
57b4053559ff libtwamr: beginning of project
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
94 int amr_frame_from_tseq(const uint16_t *cod, int use_rxtype,
57b4053559ff libtwamr: beginning of project
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
95 struct amr_param_frame *frame);
57b4053559ff libtwamr: beginning of project
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
96
464
fa0652115168 libtwamr: add amr_dhf_subst_efr2()
Mychaela Falconia <falcon@freecalypso.org>
parents: 442
diff changeset
97 /* stateless function and const data for DHF detection */
354
e4ce7972737f libtwamr: add DHF tables
Mychaela Falconia <falcon@freecalypso.org>
parents: 307
diff changeset
98
e4ce7972737f libtwamr: add DHF tables
Mychaela Falconia <falcon@freecalypso.org>
parents: 307
diff changeset
99 int amr_check_dhf(const struct amr_param_frame *frame, int first_sub_only);
e4ce7972737f libtwamr: add DHF tables
Mychaela Falconia <falcon@freecalypso.org>
parents: 307
diff changeset
100
e4ce7972737f libtwamr: add DHF tables
Mychaela Falconia <falcon@freecalypso.org>
parents: 307
diff changeset
101 extern const int16_t amr_dhf_mr475[AMR_MAX_PRM];
e4ce7972737f libtwamr: add DHF tables
Mychaela Falconia <falcon@freecalypso.org>
parents: 307
diff changeset
102 extern const int16_t amr_dhf_mr515[AMR_MAX_PRM];
e4ce7972737f libtwamr: add DHF tables
Mychaela Falconia <falcon@freecalypso.org>
parents: 307
diff changeset
103 extern const int16_t amr_dhf_mr59[AMR_MAX_PRM];
e4ce7972737f libtwamr: add DHF tables
Mychaela Falconia <falcon@freecalypso.org>
parents: 307
diff changeset
104 extern const int16_t amr_dhf_mr67[AMR_MAX_PRM];
e4ce7972737f libtwamr: add DHF tables
Mychaela Falconia <falcon@freecalypso.org>
parents: 307
diff changeset
105 extern const int16_t amr_dhf_mr74[AMR_MAX_PRM];
e4ce7972737f libtwamr: add DHF tables
Mychaela Falconia <falcon@freecalypso.org>
parents: 307
diff changeset
106 extern const int16_t amr_dhf_mr795[AMR_MAX_PRM];
e4ce7972737f libtwamr: add DHF tables
Mychaela Falconia <falcon@freecalypso.org>
parents: 307
diff changeset
107 extern const int16_t amr_dhf_mr102[AMR_MAX_PRM];
e4ce7972737f libtwamr: add DHF tables
Mychaela Falconia <falcon@freecalypso.org>
parents: 307
diff changeset
108 extern const int16_t amr_dhf_mr122[AMR_MAX_PRM];
e4ce7972737f libtwamr: add DHF tables
Mychaela Falconia <falcon@freecalypso.org>
parents: 307
diff changeset
109 extern const int16_t amr_dhf_gsmefr[AMR_MAX_PRM];
e4ce7972737f libtwamr: add DHF tables
Mychaela Falconia <falcon@freecalypso.org>
parents: 307
diff changeset
110
464
fa0652115168 libtwamr: add amr_dhf_subst_efr2()
Mychaela Falconia <falcon@freecalypso.org>
parents: 442
diff changeset
111 /* DHF transformation on encoder output, for AMR-EFR emulation */
fa0652115168 libtwamr: add amr_dhf_subst_efr2()
Mychaela Falconia <falcon@freecalypso.org>
parents: 442
diff changeset
112
fa0652115168 libtwamr: add amr_dhf_subst_efr2()
Mychaela Falconia <falcon@freecalypso.org>
parents: 442
diff changeset
113 void amr_dhf_subst_efr(struct amr_param_frame *frame);
fa0652115168 libtwamr: add amr_dhf_subst_efr2()
Mychaela Falconia <falcon@freecalypso.org>
parents: 442
diff changeset
114 void amr_dhf_subst_efr2(struct amr_param_frame *frame, const int16_t *pcm);
fa0652115168 libtwamr: add amr_dhf_subst_efr2()
Mychaela Falconia <falcon@freecalypso.org>
parents: 442
diff changeset
115
442
6fa27df6903b libtwamr: add file header public const datum
Mychaela Falconia <falcon@freecalypso.org>
parents: 428
diff changeset
116 /* public const datum: RFC 4867 file header */
6fa27df6903b libtwamr: add file header public const datum
Mychaela Falconia <falcon@freecalypso.org>
parents: 428
diff changeset
117
6fa27df6903b libtwamr: add file header public const datum
Mychaela Falconia <falcon@freecalypso.org>
parents: 428
diff changeset
118 extern const uint8_t amr_file_header_magic[AMR_IETF_HDR_LEN];
6fa27df6903b libtwamr: add file header public const datum
Mychaela Falconia <falcon@freecalypso.org>
parents: 428
diff changeset
119
252
57b4053559ff libtwamr: beginning of project
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
120 #endif /* include guard */