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_MEDIA_METADATA_EXTRACTOR_H__
18 #define __TIZEN_MEDIA_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.
42 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
43 * @remarks You must release @a metadata using metadata_extractor_destroy().
45 * @param[in] metadata The handle to metadata
46 * @return @c 0 on success,
47 * 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 Not enough memory is available
51 * @retval #METADATA_EXTRACTOR_ERROR_PERMISSION_DENIED Permission denied
52 * @see metadata_extractor_destroy()
54 int metadata_extractor_create(metadata_extractor_h *metadata);
57 * @brief Sets the file path to extract.
58 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
59 * @param [in] metadata The handle to metadata
60 * @param [in] path The path to extract metadata
61 * @return @c 0 on success,
62 * otherwise a negative error value
63 * @retval #METADATA_EXTRACTOR_ERROR_NONE Successful
64 * @retval #METADATA_EXTRACTOR_ERROR_INVALID_PARAMETER Invalid parameter
65 * @retval #METADATA_EXTRACTOR_ERROR_FILE_EXISTS File does not exist
66 * @retval #METADATA_EXTRACTOR_ERROR_OPERATION_FAILED Internal operation failed
67 * @retval #METADATA_EXTRACTOR_ERROR_PERMISSION_DENIED Permission denied
68 * @pre Create a metadata handle by calling metadata_extractor_create().
69 * @see metadata_extractor_create()
70 * @see metadata_extractor_destroy()
72 int metadata_extractor_set_path(metadata_extractor_h metadata, const char *path);
75 * @brief Sets the buffer to extract.
76 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
77 * @param [in] metadata The handle to metadata
78 * @param [in] buffer The buffer to extract metadata
79 * @param [in] size The buffer size
80 * @return @c 0 on success,
81 * otherwise a negative error value
82 * @retval #METADATA_EXTRACTOR_ERROR_NONE Successful
83 * @retval #METADATA_EXTRACTOR_ERROR_INVALID_PARAMETER Invalid parameter
84 * @retval #METADATA_EXTRACTOR_ERROR_OPERATION_FAILED Internal operation failed
85 * @retval #METADATA_EXTRACTOR_ERROR_PERMISSION_DENIED Permission denied
86 * @pre Create a metadata handle by calling metadata_extractor_create().
87 * @see metadata_extractor_create()
88 * @see metadata_extractor_destroy()
90 int metadata_extractor_set_buffer(metadata_extractor_h metadata, const void *buffer, int size);
93 * @brief Destroys metadata.
94 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
95 * @param [in] metadata The handle to metadata
96 * @return @c 0 on success,
97 * otherwise a negative error value
98 * @retval #METADATA_EXTRACTOR_ERROR_NONE Successful
99 * @retval #METADATA_EXTRACTOR_ERROR_INVALID_PARAMETER Invalid parameter
100 * @retval #METADATA_EXTRACTOR_ERROR_OPERATION_FAILED Internal operation failed
101 * @retval #METADATA_EXTRACTOR_ERROR_PERMISSION_DENIED Permission denied
102 * @pre Create a metadata handle by calling metadata_extractor_create().
103 * @see metadata_extractor_create()
105 int metadata_extractor_destroy(metadata_extractor_h metadata);
108 * @brief Gets metadata.
109 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
111 * @remarks You must release @a value using @c free(). \n
112 * In case of accessing specific path in internal storage or external storage, you may add the privilege for accessing the path. \n
113 * For example, if you get the specific path by using storage_get_directory(). you should add previlege http://tizen.org/privilege/mediastorage or http://tizen.org/privilege/externalstorage.
115 * @param[in] metadata The handle to metadata
116 * @param[in] attribute The key attribute name to get
117 * @param[out] value The value of the attribute
118 * @return @c 0 on success,
119 * otherwise a negative error value
120 * @retval #METADATA_EXTRACTOR_ERROR_NONE Successful
121 * @retval #METADATA_EXTRACTOR_ERROR_INVALID_PARAMETER Invalid parameter
122 * @retval #METADATA_EXTRACTOR_ERROR_OUT_OF_MEMORY Not enough memory is available
123 * @retval #METADATA_EXTRACTOR_ERROR_OPERATION_FAILED Internal operation failed
124 * @retval #METADATA_EXTRACTOR_ERROR_PERMISSION_DENIED Permission denied
125 * @pre Set the path to extract by calling metadata_extractor_set_path().
126 * @see metadata_extractor_create()
127 * @see metadata_extractor_destroy()
129 int metadata_extractor_get_metadata(metadata_extractor_h metadata, metadata_extractor_attr_e attribute, char **value);
132 * @brief Gets the artwork image in a media file.
133 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
135 * @remarks You must release @a artwork and @a artwork_mime using @c free(). \n
136 * In case of accessing specific path in internal storage or external storage, you may add the privilege for accessing the path. \n
137 * For example, if you get the specific path by using storage_get_directory(). you should add previlege http://tizen.org/privilege/mediastorage or http://tizen.org/privilege/externalstorage.
139 * @param[in] metadata The handle to metadata
140 * @param[out] artwork The encoded artwork image
141 * @param[out] size The encoded artwork size
142 * @param[out] mime_type The mime type of artwork
143 * @return @c 0 on success,
144 * otherwise a negative error value
145 * @retval #METADATA_EXTRACTOR_ERROR_NONE Successful
146 * @retval #METADATA_EXTRACTOR_ERROR_INVALID_PARAMETER Invalid parameter
147 * @retval #METADATA_EXTRACTOR_ERROR_OUT_OF_MEMORY Not enough memory is available
148 * @retval #METADATA_EXTRACTOR_ERROR_OPERATION_FAILED Internal operation failed
149 * @retval #METADATA_EXTRACTOR_ERROR_PERMISSION_DENIED Permission denied
150 * @pre Set the path to extract by calling metadata_extractor_set_path().
151 * @see metadata_extractor_create()
152 * @see metadata_extractor_destroy()
154 int metadata_extractor_get_artwork(metadata_extractor_h metadata, void **artwork, int *size, char **mime_type);
157 * @brief Gets the frame of a video media file.
158 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
160 * @remarks You must release @a frame using @c free().
161 * In case of accessing specific path in internal storage or external storage, you may add the privilege for accessing the path. \n
162 * For example, if you get the specific path by using storage_get_directory(). you should add previlege http://tizen.org/privilege/mediastorage or http://tizen.org/privilege/externalstorage.
164 * @param[in] metadata The handle to metadata
165 * @param[out] frame The raw frame data in RGB888
166 * @param[out] size The frame data size
167 * @return @c 0 on success,
168 * otherwise a negative error value
169 * @retval #METADATA_EXTRACTOR_ERROR_NONE Successful
170 * @retval #METADATA_EXTRACTOR_ERROR_INVALID_PARAMETER Invalid parameter
171 * @retval #METADATA_EXTRACTOR_ERROR_OUT_OF_MEMORY Not enough memory is available
172 * @retval #METADATA_EXTRACTOR_ERROR_OPERATION_FAILED Internal operation failed
173 * @retval #METADATA_EXTRACTOR_ERROR_PERMISSION_DENIED Permission denied
174 * @pre Set the path to extract by calling metadata_extractor_set_path().
175 * @see metadata_extractor_create()
176 * @see metadata_extractor_destroy()
178 int metadata_extractor_get_frame(metadata_extractor_h metadata, void **frame, int *size);
181 * @brief Gets the synclyrics of a media file.
182 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
184 * @remarks You must release @a lyrics using @c free().
185 * In case of accessing specific path in internal storage or external storage, you may add the privilege for accessing the path. \n
186 * For example, if you get the specific path by using storage_get_directory(). you should add previlege http://tizen.org/privilege/mediastorage or http://tizen.org/privilege/externalstorage.
188 * @param[in] metadata The handle to metadata
189 * @param[in] index The index of time/lyrics to set
190 * @param[out] time_stamp The time information of the index
191 * @param[out] lyrics The lyrics of the index
192 * @return @c 0 on success,
193 * otherwise a negative error value
194 * @retval #METADATA_EXTRACTOR_ERROR_NONE Successful
195 * @retval #METADATA_EXTRACTOR_ERROR_INVALID_PARAMETER Invalid parameter
196 * @retval #METADATA_EXTRACTOR_ERROR_OPERATION_FAILED Internal operation failed
197 * @retval #METADATA_EXTRACTOR_ERROR_PERMISSION_DENIED Permission denied
198 * @pre Set the path to extract by calling metadata_extractor_set_path().
199 * @pre Get the time/lyrics set number by calling metadata_extractor_get_metadata(METADATA_SYNCLYRICS_NUM).
200 * @see metadata_extractor_create()
201 * @see metadata_extractor_destroy()
203 int metadata_extractor_get_synclyrics(metadata_extractor_h metadata, int index, unsigned long *time_stamp, char **lyrics);
206 * @brief Gets the frame of a video media.
207 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
209 * @remarks You must release @a frame using @c free().
210 * In case of accessing specific path in internal storage or external storage, you may add the privilege for accessing the path. \n
211 * For example, if you get the specific path by using storage_get_directory(). you should add previlege http://tizen.org/privilege/mediastorage or http://tizen.org/privilege/externalstorage.
213 * @param[in] metadata The handle to metadata
214 * @param[in] timestamp The timestamp in milliseconds
215 * @param[in] is_accurate If @c true the user can get an accurate frame for the given timestamp,\n
216 * otherwise @c false if the user can only get the nearest i-frame of the video rapidly
217 * @param[out] frame The raw frame data in RGB888
218 * @param[out] size The frame data size
219 * @return @c 0 on success,
220 * otherwise a negative error value
221 * @retval #METADATA_EXTRACTOR_ERROR_NONE Successful
222 * @retval #METADATA_EXTRACTOR_ERROR_INVALID_PARAMETER Invalid parameter
223 * @retval #METADATA_EXTRACTOR_ERROR_OUT_OF_MEMORY Not enough memory is available
224 * @retval #METADATA_EXTRACTOR_ERROR_OPERATION_FAILED Internal operation failed
225 * @retval #METADATA_EXTRACTOR_ERROR_PERMISSION_DENIED Permission denied
226 * @pre Set the path to extract by calling metadata_extractor_set_path().
227 * @see metadata_extractor_create()
228 * @see metadata_extractor_destroy()
230 int metadata_extractor_get_frame_at_time(metadata_extractor_h metadata, unsigned long timestamp, bool is_accurate, void **frame, int *size);
239 #endif /* __cplusplus */
241 #endif /* __TIZEN_MEDIA_METADATA_EXTRACTOR_H__ */