mp3stego-lib 1.1.7

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 Structure
2. Dependencies
3. Running Instructions
4. Installation

General

Background

This python library allows a 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 the selection of the optimal (that requires the minimal amount of bits to code the data) 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 selection of the used Huffman table indexes. Each frame in the MP3 file uses several Huffman tables (one per granule, channel and region - a total of 8-12 tables).

For the steganography we ordered the tables as pairs according to their similarities (from the article), and determined that each table represent the bit 0 or 1. For the sake of demonstration let us assume that the Huffman table x and the Huffman table y are a pair, and that x represents the bit 0 and y represents bit 1. To hide a bit, given that the Huffman table x has been selected as the optimal table, it is replaced with the Huffman table y if the bit is 1, otherwise the table x is selected. An inverted case will happen for original use of table y.

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 is decoded.
   • FrameHeader class: contains all the information about the current MP3 frame's header is decoded.
   • FrameSideInformation class: contains all the information about the current MP3 frame's side-information is decoded.
   • MP3Parser class: performs the decoding process while parsing 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 are used in the decoding process.
   • util file: contains all the different functions and dataclasses that other classes use frequently like mathematical calculations and bit operations.
   • 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 is encoded.
   • MP3Encoder class: performs the encoding process.
   • tables file: contains all the tables that are used in the encoding process.
   • util file: contains all the different functions and dataclasses that other classes use frequently like mathematical calculations and bit operations.
   • 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 allows the user to perform operations on given MP3 and WAV files. The possible actions are:
   • decode MP3 file to WAV file.
   • encode WAV file to MP3 file.
   • hide a string in the MP3 file.
   • reveal a string hidden in the MP3 file.
   • clean a MP3 file from hidden strings that it might hide.

You can see more information about the class hierarchy in UML.

Dependencies

1. Python 3.9+
2. NumPy
3. SciPy
4. TQDM
5. bitarray
6. numba

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 constructor of the Steganography class that determines if the information about the decoding/encoding process will be printed (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 that is 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 a 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 that determines if the wav file that is created from the decodin process will be deleted. (default value True).
• For revealing a string from a 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 hidden string to be written to.
• For cleaning MP3 file from a hidden string 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 mp3stego-lib