Metadata-Version: 2.1
Name: mp3stego-lib
Version: 0.2.9
Summary: mp3 steganography library
Home-page: https://github.com/tomershay100/mp3-steganography-lib
Author: Aviad Seady, Tomer Shay, Lee Zaid
Author-email: aviadevelops@gmail.com, tomershay100@gmail.com, lizizaid@gmail.com
License: MIT
Project-URL: Bug Tracker, https://github.com/tomershay100/mp3-steganography-lib/issues
Description: # MP3-Steganography
        
        #### Contributes
        
        * Aviad Seady ([aviadevelops@gmail.com](mailto:aviadevelops@gmail.com))
        * Tomer Shay ([tomershay100@gmail.com](mailto:tomershay100@gmail.com))
        * Lee Zaid ([lizizaid@gmail.com](mailto:lizizaid@gmail.com))
        
        This is a steganography library in python for hiding strings in mp3 files.
        
        1. [General](#General)
            - [Background](#background)
            - [Project Description](#project description)
            - [Project Structure](#project structure)
        2. [Dependencies](#dependencies)
        3. [Running Instructions](#running instructions)
        4. [Installation](#installation)
        
        ## General
        
        ### Background
        
        This python library allows the user to hide strings inside ``MP3`` files, extract the hidden strings from ``MP3`` file,
        clean a ``MP3`` file from hidden strings in it and generally allows to convert ``MP3`` files to ``WAV`` (decoding
        process) files and vice versa (encoding process).
        
        ### Project Description
        
        The steganography process uses and modifies huffman tables as presented in the research article "_High capacity
        reversible data hiding in MP3 based on Huffman table
        transformation_" (which can be found [here](https://www.aimspress.com/fileOther/PDF/MBE/mbe-16-04-158.pdf)). Quite
        simply, the idea is to be able to hide bits by changing the huffman tables. Each frame in the ``MP3`` file uses several
        huffman tables (one per granule, channel and regin - a total of 8-12 tables).
        
        Unofficially, they found pairs of tables, according to their similarities and determined that each would be for the bit
        0 or the bit 1. For the sake of demonstration let us assume that the huffman table x and the huffman y table are a pair,
        and that x is for the bit 0 and y for the bit 1. Now to hide a bit, given that the huffman table x has been used, it
        must be replaced with the huffman table y if the bit is 1 or to keep the huffman table x if the bit is 0. An inverted
        case will happen for original use of table y. Thus, all 30 huffman tables that use (out of 32) ``MP3`` files, are
        divided into pairs and each time you see a huffman table z - replace it with the huffman table that matches the next bit
        you want to hide.
        
        ### Project Structure
        
        The library is contains several packages and several classes built as follows:
        
        1. `decoder` package:
            * **Frame class:** contains all the information about the current ``MP3`` frame that been decoded.
            * **FrameHeader class:** contains all the information about the current ``MP3`` frame header that been decoded.
            * **FrameSideInformation class:** contains all the information about the current ``MP3`` frame side-information that
              been decoded.
            * **MP3Parser class:** performs the actual decoding process while going through all the frames of the file.
            * **ID3Parser class:** performs the decoding process on the ``METADATA`` of the ``MP3``` file.
            * **tables file:** contains all the tables that been used in the decoding process.
            * **util file:** contains all the different functions and dataclasses that other classes use frequently like
              mathematical calculations and bit conversions.
            * **Decoder class:** consolidates the ``MP3`` decoding process. Receives paths to files and takes
              care of the decoding process while printing information, creating files and analyzing the ``METADATA``.
        2. `encoder` package:
            * **WAVReader class:** contains all the information about the ``WAV`` file that been encoded.
            * **MP3Encoder class:** performs the actual encoding process.
            * **ID3Parser class:** performs the decoding process on the ``METADATA`` of the ``MP3``` file.
            * **tables file:** contains all the tables that been used in the encoding process.
            * **util file:** contains all the different functions and dataclasses that other classes use frequently like
              mathematical calculations and bit conversions.
            * **Encoder class:** consolidates the ``MP3`` encoding process. Receives paths to files and takes
              care of the encoding process while printing information, creating files.
        3. **Steganography class:** serves as a kind of Façade and allow the user to perform operations on his ``MP3``
           and ``WAV`` files. The possible actions are:
            * decode ``MP3`` file to ``WAV`` file.
            * encode ``WAV`` file to ``MP3`` file.
            * hide string in ``MP3`` file.
            * reveal string in ``MP3`` file.
            * clean ``MP3`` file from any string.
        
        You can see more information about the class hierarchy
        in [UML]().
        
        ## Dependencies
        
        1. [Python 3.9+](https://www.python.org/downloads/)
        2. [NumPy](https://numpy.org/install/)
        3. [SciPy](https://scipy.org/install/)
        4. [TQDM](https://github.com/tqdm/tqdm)
        5. [bitarray](https://pypi.org/project/bitarray/)
        
        you can also see in `requirements.txt` file
        
        ## Running Instructions
        
        Steganography Class API:
        
        * Creating Steganography object by
            ```python 
          from mp3stego import Steganography
          
          stego = Steganography(quiet=True)
            ```
            * ``quiet: bool``: boolean value for the function to print information or not (default value ``True``).
        * for encoding ``WAV`` file into ``MP3`` file you may use
            ```python 
            stego = Steganography(quiet=True)
            stego.encode_wav_to_mp3("input.wav", "output.mp3", 320)
            ```
            * ``wav_file_path: str``: file path for the ``WAV`` file.
            * ``output_file_path: str``: file path for the output ``MP3`` file.
            * ``bitrate: int``: the bitrate to be used in the encoding process (default value is ``320``). You may use bitrate
              from ``32Kb`` to ``420Kb`` in jumps of ``32Kb``.
        * For decoding ``MP3`` file into ``WAV`` file you may use
            ```python 
            stego = Steganography(quiet=True)
            stego.decode_mp3_to_wav("input.mp3", "output.wav")
            ```
            * ``input_file_path: str``: file path for the ``MP3`` file.
            * ``wav_file_path: str``: file path for the output ``WAV`` file (default value=```input_file_path[:-4] + ".wav"```).
        * For hiding string in ``MP3`` file you may use
            ```python 
            stego = Steganography(quiet=True)
            stego.hide_message("input.mp3", "output.mp3", "String to hide in the file")
            ```
            * ``input_file_path: str``: file path for the input ``MP3`` file.
            * ``output_file_path: str``: file path for the output ``MP3`` file.
            * ``message: str``: the message to hide in the file.
            * ``wav_file_path: str``: file path for the output ``WAV`` file (default value=```input_file_path[:-4] + ".wav"```).
            * ``delete_wav: bool``: boolean value for the decoding process to delete the wav file or not (default
              value ``True``).
        * For revealing string from ``MP3`` file you may use
            ```python 
            stego = Steganography(quiet=True)
            stego.reveal_massage("input.mp3", "results.txt")
            ```
            * ``input_file_path: str``: file path for the input ``MP3`` file.
            * ``txt_file_path: str``: file path for the results to be written to.
        * For cleaning ``MP3`` file you may use
            ```python 
            stego = Steganography(quiet=True)
            stego.clear_file("input.mp3", "output.mp3")
            ```
            * ``input_file_path: str``: file path for the input ``MP3`` file.
            * ``output_file_path: str``: file path for the output ``MP3`` file.
        
        ## Installation
        
        Install the library using:
        
        ```shell
        pip install mp3stego-lib==0.2.5
        ```
        
Platform: UNKNOWN
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.9
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
