diff --git a/src/media/audio/resampler.h b/src/media/audio/resampler.h index b6ae7c9dc..1dcfe35a1 100644 --- a/src/media/audio/resampler.h +++ b/src/media/audio/resampler.h @@ -34,7 +34,7 @@ struct SwrContext; namespace jami { /** - * Wrapper class for libswresample + * @brief Wrapper class for libswresample */ class Resampler { public: @@ -42,36 +42,49 @@ public: ~Resampler(); /** + * @brief Resample a frame. + * * Resample from @input format to @output format. + * * NOTE: sample_rate, channel_layout, and format should be set on @output */ int resample(const AVFrame* input, AVFrame* output); /** - * Wrappers around resample(AVFrame*, AVFrame*) for convenience. + * @brief Wrapper around resample(AVFrame*, AVFrame*) for convenience. */ void resample(const AudioBuffer& dataIn, AudioBuffer& dataOut); + + /** + * @brief Wrapper around resample(AVFrame*, AVFrame*) for convenience. + */ std::unique_ptr resample(std::unique_ptr&& in, const AudioFormat& out); + + /** + * @brief Wrapper around resample(AVFrame*, AVFrame*) for convenience. + */ std::shared_ptr resample(std::shared_ptr&& in, const AudioFormat& out); private: NON_COPYABLE(Resampler); /** + * @brief Reinitializes filter according to new format. + * * Reinitializes the resampler when new settings are detected. As long as both input and * output formats don't change, this will only be called once. */ void reinit(const AVFrame* in, const AVFrame* out); /** - * Libswresample resampler context. + * @brief Libswresample resampler context. * * NOTE SwrContext is an imcomplete type and cannot be stored in a smart pointer. */ SwrContext* swrCtx_; /** - * Number of times @swrCtx_ has been initialized with no successful audio resampling. + * @brief Number of times @swrCtx_ has been initialized with no successful audio resampling. * * 0: Uninitialized * 1: Initialized diff --git a/src/media/media_filter.h b/src/media/media_filter.h index 6811c968e..5e73feb90 100644 --- a/src/media/media_filter.h +++ b/src/media/media_filter.h @@ -37,7 +37,7 @@ struct AVFilterInOut; namespace jami { /** - * Provides access to libavfilter. + * @brief Provides access to libavfilter. * * Can be used for filters with unlimited number of inputs. * Multiple outputs are not supported. They add complexity for little gain. @@ -64,36 +64,38 @@ class MediaFilter { ~MediaFilter(); /** - * Returns the current filter graph string. + * @brief Returns the current filter graph string. */ std::string getFilterDesc() const; /** - * Initializes the filter graph with one or more inputs and one output. Returns a negative code on error. + * @brief Initializes the filter graph with one or more inputs and one output. Returns a negative code on error. */ int initialize(const std::string& filterDesc, std::vector msps); /** - * Returns a MediaStream object describing the input specified by @inputName. + * @brief Returns a MediaStream object describing the input specified by @inputName. */ MediaStream getInputParams(const std::string& inputName) const; /** - * Returns a MediaStream struct describing the frames that will be output. + * @brief Returns a MediaStream struct describing the frames that will be output. * * When called in an invalid state, the returned format will be invalid (less than 0). */ MediaStream getOutputParams() const; /** - * Give the specified source filter an input frame. Caller is responsible for freeing the frame. + * @brief Give the specified source filter an input frame. + * + * Caller is responsible for freeing the frame. * * NOTE Will fail if @inputName is not found in the graph. */ int feedInput(AVFrame* frame, const std::string& inputName); /** - * Pull a frame from the filter graph. Caller owns the frame reference. + * @brief Pull a frame from the filter graph. Caller owns the frame reference. * * Returns AVERROR(EAGAIN) if filter graph requires more input. * @@ -102,7 +104,7 @@ class MediaFilter { std::unique_ptr readOutput(); /** - * Flush filter to indicate EOF. + * @brief Flush filter to indicate EOF. */ void flush(); @@ -110,59 +112,67 @@ class MediaFilter { NON_COPYABLE(MediaFilter); /** - * Initializes output of filter graph. + * @brief Initializes output of filter graph. */ int initOutputFilter(AVFilterInOut* out); /** - * Initializes an input of filter graph. + * @brief Initializes an input of filter graph. */ int initInputFilter(AVFilterInOut* in, MediaStream msp); /** - * Reinitializes the filter graph with @inputParams_, which should be updated beforehand. + * @brief Reinitializes the filter graph. + * + * Reinitializes with @inputParams_, which should be updated beforehand. */ int reinitialize(); /** - * Convenience method that prints @msg and returns err. + * @brief Convenience method that prints @msg and returns err. * * NOTE @msg should not be null. */ int fail(std::string msg, int err) const; /** - * Frees resources used by MediaFilter. + * @brief Frees resources used by MediaFilter. */ void clean(); /** - * Filter graph pointer. + * @brief Filter graph pointer. */ AVFilterGraph* graph_ = nullptr; /** - * Filter graph output. Corresponds to a buffersink/abuffersink filter. + * @brief Filter graph output. + * + * Corresponds to a buffersink/abuffersink filter. */ AVFilterContext* output_ = nullptr; /** - * List of filter graph inputs. Each corresponds to a buffer/abuffer filter. + * @brief List of filter graph inputs. + * + * Each corresponds to a buffer/abuffer filter. */ std::vector inputs_; /** - * List of filter graph input parameters. Same order as @inputs_. + * @brief List of filter graph input parameters. + * + * Same order as @inputs_. */ std::vector inputParams_; /** - * Filter graph string. + * @brief Filter graph string. */ std::string desc_ {}; /** - * Flag to know whether or not the filter graph is initialized. + * @brief Flag to know whether or not the filter graph is initialized. */ bool initialized_ {false}; }; diff --git a/src/media/media_recorder.h b/src/media/media_recorder.h index 9328af698..f4cca5edf 100644 --- a/src/media/media_recorder.h +++ b/src/media/media_recorder.h @@ -45,12 +45,14 @@ public: ~MediaRecorder(); /** - * Gets whether or not the recorder is active. + * @brief Gets whether or not the recorder is active. */ bool isRecording() const; /** - * Get file path of file to be recorded. Same path as sent to @setPath, but with + * @brief Get file path of file to be recorded. + * + * Same path as sent to @setPath, but with * file extension appended. * * NOTE @audioOnly must be called to have the right extension. @@ -58,20 +60,24 @@ public: std::string getPath() const; /** + * @brief Resulting file will be audio or video. + * * Sets whether or not output file will have audio. Determines the extension of the * output file (.ogg or .webm). */ void audioOnly(bool audioOnly); /** - * Sets output file path. + * @brief Sets output file path. * * NOTE An empty path will put the output file in the working directory. */ void setPath(const std::string& path); /** - * Sets title and description metadata for the file. Uses default if either is empty. + * @brief Sets title and description metadata for the file. + * + * Uses default if either is empty. * Default title is "Conversation at %Y-%m-%d %H:%M:%S". * Default description is "Recorded with Jami https://jami.net". * @@ -80,23 +86,30 @@ public: void setMetadata(const std::string& title, const std::string& desc); /** - * Adds a stream to the recorder. Caller must then attach this to the media source. + * @brief Adds a stream to the recorder. + * + * Caller must then attach this to the media source. */ Observer>* addStream(const MediaStream& ms); /** - * Gets the stream observer so the caller can detach it from the media source. + * @brief Gets the stream observer. + * + * This is so the caller can detach it from the media source. */ Observer>* getStream(const std::string& name) const; /** - * Starts the record. Streams must have been added using Observable::attach and - * @addStream. + * @brief Initializes the file. + * + * Streams must have been added using Observable::attach and @addStream. */ int startRecording(); /** - * Stops the record. Streams must be removed using Observable::detach afterwards. + * @brief Finalizes the file. + * + * Streams must be removed using Observable::detach afterwards. */ void stopRecording(); diff --git a/src/media/video/accel.h b/src/media/video/accel.h index 628b49847..d9e777bb1 100644 --- a/src/media/video/accel.h +++ b/src/media/video/accel.h @@ -34,69 +34,81 @@ extern "C" { namespace jami { namespace video { /** - * Provides an abstraction layer to the hardware acceleration APIs in FFmpeg. + * @brief Provides an abstraction layer to the hardware acceleration APIs in FFmpeg. */ class HardwareAccel { public: /** - * Static factory method for hardware decoding. + * @brief Static factory method for hardware decoding. */ static std::unique_ptr setupDecoder(AVCodecID id, int width, int height); /** - * Static factory method for hardware encoding. + * @brief Static factory method for hardware encoding. */ static std::unique_ptr setupEncoder(AVCodecID id, int width, int height, AVBufferRef* framesCtx = nullptr); /** + * @brief Transfers hardware frame to main memory. + * * Transfers a hardware decoded frame back to main memory. Should be called after * the frame is decoded using avcodec_send_packet/avcodec_receive_frame. * - * @frame: Refrerence to the decoded hardware frame. - * @returns: Software frame. + * If @frame is software, this is a no-op. + * + * @param frame Refrerence to the decoded hardware frame. + * @param desiredFormat Software pixel format that the hardware outputs. + * @returns Software frame. */ static std::unique_ptr transferToMainMemory(const VideoFrame& frame, AVPixelFormat desiredFormat); /** + * @brief Constructs a HardwareAccel object + * * Made public so std::unique_ptr can access it. Should not be called. */ HardwareAccel(AVCodecID id, const std::string& name, AVHWDeviceType hwType, AVPixelFormat format, AVPixelFormat swFormat, CodecType type); /** - * Dereferences hardware contexts. + * @brief Dereferences hardware contexts. */ ~HardwareAccel(); /** - * Codec that is being accelerated. + * @brief Codec that is being accelerated. */ AVCodecID getCodecId() const { return id_; }; /** - * Name of the hardware layer/API being used. + * @brief Name of the hardware layer/API being used. */ std::string getName() const { return name_; }; /** - * Hardware format. + * @brief Hardware format. */ AVPixelFormat getFormat() const { return format_; }; /** - * Software format. For encoding it is the format expected by the hardware. For decoding + * @brief Software format. + * + * For encoding it is the format expected by the hardware. For decoding * it is the format output by the hardware. */ AVPixelFormat getSoftwareFormat() const { return swFormat_; } /** - * Gets the name of the codec. + * @brief Gets the name of the codec. + * * Decoding: avcodec_get_name(id_) * Encoding: avcodec_get_name(id_) + '_' + name_ */ std::string getCodecName() const; /** + * @brief If hardware decoder can feed hardware encoder directly. + * * Returns whether or not the decoder is linked to an encoder or vice-versa. Being linked * means an encoder can directly use the decoder's hardware frame, without first * transferring it to main memory. @@ -104,7 +116,9 @@ public: bool isLinked() const { return linked_; } /** - * Set some extra details in the codec context. Should be called after a successful + * @brief Set some extra details in the codec context. + * + * Should be called after a successful * setup (setupDecoder or setupEncoder). * For decoding, sets the hw_device_ctx and get_format callback. If the decoder has * a frames context, mark as linked. @@ -114,18 +128,21 @@ public: void setDetails(AVCodecContext* codecCtx); /** + * @brief Transfers a frame to/from the GPU memory. + * * Transfers a hardware decoded frame back to main memory. Should be called after * the frame is decoded using avcodec_send_packet/avcodec_receive_frame or before * the frame is encoded using avcodec_send_frame/avcodec_receive_packet. * - * @frame: Hardware frame when decoding, software frame when encoding. - * @returns: Software frame when decoding, hardware frame when encoding. + * @param frame Hardware frame when decoding, software frame when encoding. + * @returns Software frame when decoding, hardware frame when encoding. */ std::unique_ptr transfer(const VideoFrame& frame); /** - * Links this HardwareAccel's frames context with the passed in context. This serves - * to skip transferring a decoded frame back to main memory before encoding. + * @brief Links this HardwareAccel's frames context with the passed in context. + * + * This serves to skip transferring a decoded frame back to main memory before encoding. */ bool linkHardware(AVBufferRef* framesCtx);