2 * Sonitus - Filter.java - Copyright © 2013 David Roden
4 * This program is free software: you can redistribute it and/or modify
5 * it under the terms of the GNU General Public License as published by
6 * the Free Software Foundation, either version 3 of the License, or
7 * (at your option) any later version.
9 * This program is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12 * GNU General Public License for more details.
14 * You should have received a copy of the GNU General Public License
15 * along with this program. If not, see <http://www.gnu.org/licenses/>.
18 package net.pterodactylus.sonitus.data;
20 import java.io.IOException;
21 import java.util.List;
24 * A filter is both a source and a sink for audio data. It is used to process
25 * the audio date in whatever way seems appropriate.
27 * @author <a href="mailto:bombe@pterodactylus.net">David ‘Bombe’ Roden</a>
29 public interface Filter {
32 * Adds the given listener to the list of registered listeners.
34 * @param metadataListener
35 * The metadata listener to add
37 void addMetadataListener(MetadataListener metadataListener);
40 * Removes the given listener from the list of registered listeners.
42 * @param metadataListener
43 * The metadata listener to remove
45 void removeMetadataListener(MetadataListener metadataListener);
48 * Returns the name of this filter.
50 * @return The name of this filter
55 * Returns the controllers offered by this filter.
57 * @return The controllers of this filter
59 List<Controller<?>> controllers();
62 * Returns the metadata of the audio stream.
64 * @return The metadata of the audio stream
69 * Notifies the sink that the metadata of the audio stream has changed. This
70 * method should return as fast as possible, i.e. every heavy lifting should be
71 * done from another thread.
76 void metadataUpdated(Metadata metadata);
79 * Retrieves data from the audio stream.
82 * The maximum amount of bytes to retrieve from the audio stream
83 * @return A data packet containing the metadata of the stream (optional) and
84 * the buffer filled with up to {@code bufferSize} bytes of data; the
85 * returned buffer may contain less data than requested but will not
86 * contain excess elements (i.e. it can be smaller than the requested
89 * if an I/O error occurs
91 DataPacket get(int bufferSize) throws IOException;
94 * Opens this sink using the format parameters of the given metadata.
97 * The metadata of the stream
99 * if an I/O error occurs
101 void open(Metadata metadata) throws IOException;
103 /** Closes this sink. */
107 * Processes the given data packet.
110 * The data to process
111 * @throws IOException
112 * if an I/O error occurs
114 void process(DataPacket dataPacket) throws IOException;