2 * Copyright (c) 2011 Samsung Electronics Co., Ltd All Rights Reserved
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
8 * http://www.apache.org/licenses/LICENSE-2.0
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
17 #ifndef __TIZEN_MULTIMEDIA_METADATA_EXTRACTOR_H__
18 #define __TIZEN_MULTIMEDIA_METADATA_EXTRACTOR_H__
22 #include <metadata_extractor_type.h>
27 #endif /* __cplusplus */
30 * @file metadata_extractor.h
31 * @brief This file contains the multimedia content metadata extractor API and related structure and enumeration.
32 * It also contains the description of metadata: duration, bitrate, album, artist, author, genre, description, and so on.
36 * @addtogroup CAPI_METADATA_EXTRACTOR_MODULE
41 * @brief Creates metadata.
43 * @remarks The @a metadata should be released using metadata_extractor_destroy().
45 * @param[in] metadata The handle to metadata
47 * @return @c 0 on success, otherwise a negative error value
48 * @retval #METADATA_EXTRACTOR_ERROR_NONE Successful
49 * @retval #METADATA_EXTRACTOR_ERROR_INVALID_PARAMETER Invalid parameter
50 * @retval #METADATA_EXTRACTOR_ERROR_OUT_OF_MEMORY Out of memory
52 * @see metadata_extractor_destroy()
54 int metadata_extractor_create(metadata_extractor_h *metadata);
57 * @brief Sets the file path to extract.
60 * @param[in] metadata The handle to metadata
61 * @param[in] path The path to extract metadata
63 * @return @c 0 on success, otherwise a negative error value
64 * @retval #METADATA_EXTRACTOR_ERROR_NONE Successful
65 * @retval #METADATA_EXTRACTOR_ERROR_INVALID_PARAMETER Invalid parameter
66 * @retval #METADATA_EXTRACTOR_ERROR_FILE_EXISTS File does not exist
67 * @retval #METADATA_EXTRACTOR_ERROR_OPERATION_FAILED Internal operation failed
69 * @pre Create a metadata handle by calling metadata_extractor_create().
70 * @see metadata_extractor_create()
71 * @see metadata_extractor_destroy()
73 int metadata_extractor_set_path(metadata_extractor_h metadata, const char *path);
76 * @brief Sets the buffer to extract.
79 * @param[in] metadata The handle to metadata
80 * @param[in] buffer The buffer to extract metadata
81 * @param[in] size The buffer size
83 * @return @c 0 on success, otherwise a negative error value
84 * @retval #METADATA_EXTRACTOR_ERROR_NONE Successful
85 * @retval #METADATA_EXTRACTOR_ERROR_INVALID_PARAMETER Invalid parameter
86 * @retval #METADATA_EXTRACTOR_ERROR_OPERATION_FAILED Internal operation failed
88 * @pre Create a metadata handle by calling metadata_extractor_create().
89 * @see metadata_extractor_create()
90 * @see metadata_extractor_destroy()
92 int metadata_extractor_set_buffer(metadata_extractor_h metadata, const void *buffer, int size);
95 * @brief Destroys metadata.
98 * @param[in] metadata The handle to metadata
100 * @return @c 0 on success, otherwise a negative error value
101 * @retval #METADATA_EXTRACTOR_ERROR_NONE Successful
102 * @retval #METADATA_EXTRACTOR_ERROR_INVALID_PARAMETER Invalid parameter
103 * @retval #METADATA_EXTRACTOR_ERROR_OPERATION_FAILED Internal operation failed
105 * @pre Create a metadata handle by calling metadata_extractor_create().
106 * @see metadata_extractor_create()
108 int metadata_extractor_destroy(metadata_extractor_h metadata);
111 * @brief Gets metadata.
114 * @remarks The @a value should be released using free(). \n
115 * In case of accessing specific path in internal storage or external storage, you may add the privilege for accessing the path. \n
116 * For example, if you get the specific path by using storage_get_directory(). you should add privilege %http://tizen.org/privilege/mediastorage or %http://tizen.org/privilege/externalstorage.
118 * @param[in] metadata The handle to metadata
119 * @param[in] attribute The key attribute name to get
120 * @param[out] value The value of the attribute
122 * @return @c 0 on success, otherwise a negative error value
123 * @retval #METADATA_EXTRACTOR_ERROR_NONE Successful
124 * @retval #METADATA_EXTRACTOR_ERROR_INVALID_PARAMETER Invalid parameter
125 * @retval #METADATA_EXTRACTOR_ERROR_OUT_OF_MEMORY Out of memory
126 * @retval #METADATA_EXTRACTOR_ERROR_OPERATION_FAILED Internal operation failed
127 * @retval #METADATA_EXTRACTOR_ERROR_PERMISSION_DENIED Permission denied
129 * @pre Set the path to extract by calling metadata_extractor_set_path().
130 * @see metadata_extractor_create()
131 * @see metadata_extractor_destroy()
133 int metadata_extractor_get_metadata(metadata_extractor_h metadata, metadata_extractor_attr_e attribute, char **value);
136 * @brief Gets the artwork image in a media file.
139 * @remarks The @a artwork and @a mime_type should be released using free(). \n
140 * In case of accessing specific path in internal storage or external storage, you may add the privilege for accessing the path. \n
141 * For example, if you get the specific path by using storage_get_directory(). you should add privilege %http://tizen.org/privilege/mediastorage or %http://tizen.org/privilege/externalstorage.
143 * @param[in] metadata The handle to metadata
144 * @param[out] artwork The encoded artwork image
145 * @param[out] size The encoded artwork size
146 * @param[out] mime_type The MIME of the artwork
147 * @return @c 0 on success, otherwise a negative error value
149 * @retval #METADATA_EXTRACTOR_ERROR_NONE Successful
150 * @retval #METADATA_EXTRACTOR_ERROR_INVALID_PARAMETER Invalid parameter
151 * @retval #METADATA_EXTRACTOR_ERROR_OUT_OF_MEMORY Out of memory
152 * @retval #METADATA_EXTRACTOR_ERROR_OPERATION_FAILED Internal operation failed
153 * @retval #METADATA_EXTRACTOR_ERROR_PERMISSION_DENIED Permission denied
155 * @pre Set the path to extract by calling metadata_extractor_set_path().
156 * @see metadata_extractor_create()
157 * @see metadata_extractor_destroy()
159 int metadata_extractor_get_artwork(metadata_extractor_h metadata, void **artwork, int *size, char **mime_type);
162 * @brief Gets the frame of a video media file.
165 * @remarks The @a frame should be released using free().
166 * In case of accessing specific path in internal storage or external storage, you may add the privilege for accessing the path. \n
167 * For example, if you get the specific path by using storage_get_directory(). you should add privilege %http://tizen.org/privilege/mediastorage or %http://tizen.org/privilege/externalstorage.
169 * @param[in] metadata The handle to metadata
170 * @param[out] frame The raw frame data in RGB888
171 * @param[out] size The frame data size
173 * @return @c 0 on success, otherwise a negative error value
174 * @retval #METADATA_EXTRACTOR_ERROR_NONE Successful
175 * @retval #METADATA_EXTRACTOR_ERROR_INVALID_PARAMETER Invalid parameter
176 * @retval #METADATA_EXTRACTOR_ERROR_OUT_OF_MEMORY Out of memory
177 * @retval #METADATA_EXTRACTOR_ERROR_OPERATION_FAILED Internal operation failed
178 * @retval #METADATA_EXTRACTOR_ERROR_PERMISSION_DENIED Permission denied
180 * @pre Set the path to extract by calling metadata_extractor_set_path().
181 * @see metadata_extractor_create()
182 * @see metadata_extractor_destroy()
184 int metadata_extractor_get_frame(metadata_extractor_h metadata, void **frame, int *size);
187 * @brief Gets the synclyrics of a media file.
190 * @remarks The @a lyrics should be released using free().
191 * In case of accessing specific path in internal storage or external storage, you may add the privilege for accessing the path. \n
192 * For example, if you get the specific path by using storage_get_directory(). you should add privilege %http://tizen.org/privilege/mediastorage or %http://tizen.org/privilege/externalstorage.
194 * @param[in] metadata The handle to metadata
195 * @param[in] index The index of time/lyrics to set
196 * @param[out] time_stamp The time information of the index
197 * @param[out] lyrics The lyrics of the index
199 * @return @c 0 on success, otherwise a negative error value
200 * @retval #METADATA_EXTRACTOR_ERROR_NONE Successful
201 * @retval #METADATA_EXTRACTOR_ERROR_INVALID_PARAMETER Invalid parameter
202 * @retval #METADATA_EXTRACTOR_ERROR_OPERATION_FAILED Internal operation failed
203 * @retval #METADATA_EXTRACTOR_ERROR_PERMISSION_DENIED Permission denied
205 * @pre Set the path to extract by calling metadata_extractor_set_path().
206 * @pre Get the time/lyrics set number by calling metadata_extractor_get_metadata(METADATA_SYNCLYRICS_NUM).
207 * @see metadata_extractor_create()
208 * @see metadata_extractor_destroy()
210 int metadata_extractor_get_synclyrics(metadata_extractor_h metadata, int index, unsigned long *time_stamp, char **lyrics);
213 * @brief Gets the frame of a video media.
216 * @remarks The @a frame should be released using free().
217 * In case of accessing specific path in internal storage or external storage, you may add the privilege for accessing the path. \n
218 * For example, if you get the specific path by using storage_get_directory(). you should add privilege %http://tizen.org/privilege/mediastorage or %http://tizen.org/privilege/externalstorage.
220 * @param[in] metadata The handle to metadata
221 * @param[in] timestamp The timestamp in milliseconds
222 * @param[in] is_accurate If @c true the user can get an accurate frame for the given timestamp,\n
223 * otherwise @c false if the user can only get the nearest i-frame of the video rapidly
224 * @param[out] frame The raw frame data in RGB888
225 * @param[out] size The frame data size
227 * @return @c 0 on success, otherwise a negative error value
228 * @retval #METADATA_EXTRACTOR_ERROR_NONE Successful
229 * @retval #METADATA_EXTRACTOR_ERROR_INVALID_PARAMETER Invalid parameter
230 * @retval #METADATA_EXTRACTOR_ERROR_OUT_OF_MEMORY Out of memory
231 * @retval #METADATA_EXTRACTOR_ERROR_OPERATION_FAILED Internal operation failed
232 * @retval #METADATA_EXTRACTOR_ERROR_PERMISSION_DENIED Permission denied
234 * @pre Set the path to extract by calling metadata_extractor_set_path().
235 * @see metadata_extractor_create()
236 * @see metadata_extractor_destroy()
238 int metadata_extractor_get_frame_at_time(metadata_extractor_h metadata, unsigned long timestamp, bool is_accurate, void **frame, int *size);
247 #endif /* __cplusplus */
249 #endif /* __TIZEN_MULTIMEDIA_METADATA_EXTRACTOR_H__ */