1#!/usr/bin/env python2
2# Copyright 2014 The Chromium OS Authors. All rights reserved.
3# Use of this source code is governed by a BSD-style license that can be
4# found in the LICENSE file.
5
6"""This module provides abstraction of audio data."""
7
8from __future__ import absolute_import
9from __future__ import division
10from __future__ import print_function
11import contextlib
12import copy
13import numpy as np
14import struct
15from six.moves import range
16import six
17
18
19"""The dict containing information on how to parse sample from raw data.
20
21Keys: The sample format as in aplay command.
22Values: A dict containing:
23    message: Human-readable sample format.
24    dtype_str: Data type used in numpy dtype.  Check
25               https://docs.scipy.org/doc/numpy/reference/arrays.dtypes.html
26               for supported data type.
27    size_bytes: Number of bytes for one sample.
28"""
29SAMPLE_FORMATS = dict(
30        S32_LE=dict(
31                message='Signed 32-bit integer, little-endian',
32                dtype_str='<i',
33                size_bytes=4),
34        S16_LE=dict(
35                message='Signed 16-bit integer, little-endian',
36                dtype_str='<i',
37                size_bytes=2))
38
39
40def get_maximum_value_from_sample_format(sample_format):
41    """Gets the maximum value from sample format.
42
43    @param sample_format: A key in SAMPLE_FORMAT.
44
45    @returns: The maximum value the sample can hold + 1.
46
47    """
48    size_bits = SAMPLE_FORMATS[sample_format]['size_bytes'] * 8
49    return 1 << (size_bits - 1)
50
51
52class AudioRawDataError(Exception):
53    """Error in AudioRawData."""
54    pass
55
56
57class AudioRawData(object):
58    """The abstraction of audio raw data.
59
60    @property channel: The number of channels.
61    @property channel_data: A list of lists containing samples in each channel.
62                            E.g., The third sample in the second channel is
63                            channel_data[1][2].
64    @property sample_format: The sample format which should be one of the keys
65                             in audio_data.SAMPLE_FORMATS.
66    """
67    def __init__(self, binary, channel, sample_format):
68        """Initializes an AudioRawData.
69
70        @param binary: A string containing binary data. If binary is not None,
71                       The samples in binary will be parsed and be filled into
72                       channel_data.
73        @param channel: The number of channels.
74        @param sample_format: One of the keys in audio_data.SAMPLE_FORMATS.
75        """
76        self.channel = channel
77        self.channel_data = [[] for _ in range(self.channel)]
78        self.sample_format = sample_format
79        if binary:
80            self.read_binary(binary)
81
82
83    def read_binary(self, binary):
84        """Reads samples from binary and fills channel_data.
85
86        Reads samples of fixed width from binary string into a numpy array
87        and shapes them into each channel.
88
89        @param binary: A string containing binary data.
90        """
91        sample_format_dict = SAMPLE_FORMATS[self.sample_format]
92
93        # The data type used in numpy fromstring function. For example,
94        # <i4 for 32-bit signed int.
95        np_dtype = '%s%d' % (sample_format_dict['dtype_str'],
96                             sample_format_dict['size_bytes'])
97
98        # Reads data from a string into 1-D array.
99        np_array = np.fromstring(binary, dtype=np_dtype)
100        n_frames = len(np_array) // self.channel
101        # Reshape np_array into an array of shape (n_frames, channel).
102        np_array = np_array.reshape(n_frames, self.channel)
103        # Transpose np_arrya so it becomes of shape (channel, n_frames).
104        self.channel_data = np_array.transpose()
105