mp3stego-lib 0.2.5

mp3 steganography library

MP3-Steganography

Contributes

• Aviad Seady ([e-mail])
• Tomer Shay ([e-mail])
• Lee Zaid ([e-mail])

This is a steganography library in python for hiding strings in mp3 files.

1. General
   • Background
   • Project Description
   • Project Stucture
2. Dependencies
3. [Running Instructions](#running instructions)
4. 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). 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+
2. NumPy
3. SciPy
4. TQDM
5. bitarray

you can also see in requirements.txt file

Running Instructions

Steganography Class API:

• Creating Steganography object by

  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

  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

  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

  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

  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

  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:

pip install -i https://test.pypi.org/simple/ mp3stego-lib==0.2.3